feat: convert websockets to server-side events (#1587)

* refactor: transition from WebSocket to Server-Sent Events (SSE) for real-time updates

- Updated documentation and codebase to replace WebSocket references with SSE, enhancing the real-time communication mechanism.
- Modified AGENTS.md, README, and various architecture documents to reflect the shift to SSE for Google Calendar sync and event notifications.
- Introduced a new feature document for Google Sync and SSE, detailing the architecture and event flow.
- Removed obsolete WebSocket code and dependencies from the backend, ensuring a cleaner and more maintainable codebase.
- Updated tests and hooks to utilize SSE, ensuring consistent behavior across the application.

* chore(deps): update dependencies in yarn.lock

- Updated "@adobe/css-tools" to version 4.4.4.
- Removed obsolete "socket.io" and "socket.io-client" dependencies.
- Updated "@emnapi/core" and "@emnapi/runtime" to version 1.9.1.
- Updated "@napi-rs/wasm-runtime" to version 1.1.2 with peer dependencies.
- Bumped "@opentelemetry/api" to version 1.9.1 and "@opentelemetry/core" to version 2.6.1.
- Updated "@posthog/core" to version 1.24.3 and "@posthog/types" to version 1.364.1.
- Updated "@sinclair/typebox" to version 0.34.49 and "@tanstack/react-store" to version 0.9.3.
- Updated "@tanstack/store" to version 0.9.3.

* feat(webpack): add alias for Server-Sent Events (SSE) module

- Introduced an alias for the SSE module in the webpack configuration, enhancing module resolution and improving code organization.

* fix(loaders): handle SuperTokens session checks in test environment

- Added a condition in the loadAuthenticated function to return an unauthenticated state when NODE_ENV is set to "test", preventing session checks from blocking navigation during Playwright e2e tests.

* refactor(sse): transition to EventEmitter for SSE event handling

- Replaced direct EventSource event listeners with an EventEmitter2 instance for improved event management.
- Updated hooks to utilize the new sseEmitter for handling SSE events, enhancing modularity and maintainability.
- Refactored tests to accommodate the changes in event handling, ensuring consistent behavior across the application.

* refactor(sse): update USER_METADATA publishing method and enhance test coverage

- Changed the USER_METADATA publishing method in the SSE server to use a response object, improving the handling of server-sent events.
- Added a test to ensure that USER_METADATA is not replayed to existing tabs when a new tab opens, enhancing the reliability of the SSE implementation.

* refactor(base.driver): streamline event handling in BaseDriver class

- Moved the initialization of eventName and dataLine variables outside the loop in the BaseDriver class, improving code clarity and reducing redundancy.
- Updated the test file for SSE server to remove redundant comments, enhancing readability while maintaining the test environment setup.

* fix(events): ensure proper response handling for SSE stream errors

- Added a check to send a 500 status response if an error occurs while opening the SSE stream and headers have not been sent, improving error handling in the EventsController.
- Removed obsolete socket alias from jest configuration, streamlining module resolution for the web project.

* refactor(sse): improve connection management in SSE server

- Updated the connection handling logic in the SSE server to utilize a dedicated method for removing dead connections, enhancing code clarity and maintainability.
- Refactored the subscription and error handling processes to ensure proper cleanup of connections, improving overall reliability of the SSE implementation.

Author: tyler-dane

AGENTS.md

@@ -123,7 +123,7 @@ This is a Typescript project with a monorepo structure.
 
 ### Packages Overview
 
-- `@compass/backend` - Express.js REST API with MongoDB, Google Calendar sync, WebSocket support
+- `@compass/backend` - Express.js REST API with MongoDB, Google Calendar sync, Server-Sent Events (SSE)
 - `@compass/web` - React/TypeScript frontend with Redux, styled-components, webpack bundling
 - `@compass/core` - Shared utilities, types, and business logic
 - `@compass/scripts` - CLI tools for building, database operations, user management

docs/README.md

@@ -16,7 +16,7 @@ Start with [AGENTS.md](../AGENTS.md) for repo rules, commands, and conventions.
 - Auth or session behavior:
   [Frontend Runtime Flow](./frontend/frontend-runtime-flow.md),
   [Password Auth Flow](./features/password-auth-flow.md),
-  [Google Sync And Websocket Flow](./features/google-sync-and-websocket-flow.md)
+  [Google Sync And SSE Flow](./features/google-sync-and-sse-flow.md)
 - Event shape or recurrence behavior:
   [Event And Task Domain Model](./architecture/event-and-task-domain-model.md),
   [Recurrence Handling](./features/recurring-events-handling.md)
@@ -30,7 +30,7 @@ Start with [AGENTS.md](../AGENTS.md) for repo rules, commands, and conventions.
 ## Runtime Flows
 
 - [Frontend Runtime Flow](./frontend/frontend-runtime-flow.md)
-- [Google Sync And Websocket Flow](./features/google-sync-and-websocket-flow.md)
+- [Google Sync And SSE Flow](./features/google-sync-and-sse-flow.md)
 - [Password Auth Flow](./features/password-auth-flow.md)
 
 ## Architecture And Domain
@@ -52,6 +52,6 @@ Start with [AGENTS.md](../AGENTS.md) for repo rules, commands, and conventions.
 ## Feature Deep Dives
 
 - [Password Auth Flow](./features/password-auth-flow.md)
-- [Google Sync And Websocket Flow](./features/google-sync-and-websocket-flow.md)
+- [Google Sync And SSE Flow](./features/google-sync-and-sse-flow.md)
 - [Recurrence Handling](./features/recurring-events-handling.md)
 - [Offline Storage And Migrations](./features/offline-storage-and-migrations.md)

docs/architecture/event-and-task-domain-model.md

@@ -85,7 +85,7 @@ It affects:
 
 - query behavior
 - sync transitions
-- websocket notification type
+- SSE notification type
 - provider selection when mapping events
 
 For someday events, Compass often behaves as the provider of record instead of Google.

docs/architecture/glossary.md

@@ -51,7 +51,7 @@ Definition of terms used in the source code and documentation.
 
 **Duck Pattern**: A Redux pattern that co-locates actions, reducers, and selectors in a single file (or directory) for a feature domain.
 
-**WebSocket**: A communication protocol used for real-time bidirectional communication between the frontend and backend. Used to push updates when events change.
+**Server-Sent Events (SSE)**: An HTTP-based mechanism where the server pushes named events over a long-lived response. Compass uses one `EventSource` per tab to `GET /api/events/stream` for calendar sync and metadata updates.
 
 **Supertokens**: The authentication library used by Compass to manage user sessions, access tokens, and refresh tokens.
 

docs/architecture/repo-architecture.md

@@ -12,7 +12,7 @@ The React frontend. It owns:
 - auth/session-aware UI
 - event and task interactions
 - local offline storage
-- websocket listeners
+- SSE listeners (`EventSource`)
 
 Key entrypoints:
 
@@ -29,13 +29,13 @@ The Express + MongoDB backend. It owns:
 - Supertokens session enforcement
 - event CRUD and recurrence processing
 - Google Calendar sync
-- websocket fanout
+- SSE fanout
 
 Key entrypoints:
 
 - `packages/backend/src/app.ts`
 - `packages/backend/src/servers/express/express.server.ts`
-- `packages/backend/src/servers/websocket/websocket.server.ts`
+- `packages/backend/src/servers/sse/sse.server.ts`
 
 ### `packages/core`
 
@@ -51,7 +51,7 @@ High-value files:
 - `packages/core/src/types/event.types.ts`
 - `packages/core/src/types/type.utils.ts`
 - `packages/core/src/constants/core.constants.ts`
-- `packages/core/src/constants/websocket.constants.ts`
+- `packages/core/src/constants/sse.constants.ts`
 
 ### `packages/scripts`
 
@@ -73,14 +73,14 @@ The web package imports shared event/task/date concepts from `core` and should n
 
 ### Backend -> Core
 
-The backend uses `core` for shared validation, event categories, recurrence scopes, constants, and websocket event names.
+The backend uses `core` for shared validation, event categories, recurrence scopes, constants, and SSE event names.
 
 ### Web <-> Backend
 
 The web talks to the backend through:
 
 - HTTP APIs
-- websocket events
+- SSE events
 - shared domain types from `core`
 
 ## Startup Paths
@@ -102,7 +102,7 @@ The web talks to the backend through:
 
 1. create Express app
 2. create HTTP server
-3. initialize websocket server on the HTTP server
+3. register HTTP routes (SSE is opened per authenticated `GET /api/events/stream`)
 4. start Mongo
 5. listen on the configured port
 6. optionally connect ngrok
@@ -138,5 +138,5 @@ The repo prefers:
 
 - New event field: `core` schema, backend parsing/persistence, web editors/selectors/tests
 - New backend endpoint: backend route/controller/service plus maybe shared type in `core`
-- New websocket event: `core` constants/types, backend server emitter, web socket hook consumer
+- New SSE event: `core` constants/types, backend `sse.server` / `publish`, web SSE hook consumer
 - New local persistence behavior: web storage adapter, migration runner, tests

docs/backend/README.md

@@ -1,6 +1,6 @@
 # Compass Backend
 
-Backend service for auth/session management, event persistence, Google sync, and websocket notifications.
+Backend service for auth/session management, event persistence, Google sync, and SSE notifications.
 
 ## Intent
 
@@ -22,7 +22,7 @@ When changing sync or auth logic:
 - Shared error handling:
   - `packages/backend/src/common/errors/handlers/error.express.handler.ts`
 - Realtime notifications:
-  - `packages/backend/src/servers/websocket/websocket.server.ts`
+  - `packages/backend/src/servers/sse/sse.server.ts`
 
 ## Primary Backend Workflows
 
@@ -78,4 +78,4 @@ Observed outcomes include:
 - [Backend Request Flow](./backend-request-flow.md)
 - [Compass API Documentation](./api-documentation.md)
 - [Backend Error Handling](./backend-error-handling.md)
-- [Google Sync And Websocket Flow](../features/google-sync-and-websocket-flow.md)
+- [Google Sync And SSE Flow](../features/google-sync-and-sse-flow.md)

docs/backend/api-documentation.md

@@ -315,7 +315,7 @@ Authenticated user trigger for full import restart:
 
 - middleware: `verifySession()` + `requireGoogleConnectionSession`
 - response: `204 No Content`
-- import runs asynchronously; progress is surfaced via websocket `IMPORT_GCAL_START` / `IMPORT_GCAL_END`
+- import runs asynchronously; progress is surfaced via SSE `IMPORT_GCAL_START` / `IMPORT_GCAL_END`
 - body schema (`ImportGCalRequestSchema` in `packages/backend/src/sync/sync.types.ts`):
   - optional `force: boolean`
 - behavior:
@@ -325,7 +325,7 @@ Authenticated user trigger for full import restart:
 ### /api/event-change-demo
 
 - `POST /api/event-change-demo`
-- debug helper route used to dispatch event-change notifications to a configured demo socket user
+- debug helper route used to dispatch event-change notifications to the user id in env `SSE_DEBUG_USER`
 
 ### ${SYNC_DEBUG}/import-incremental/:userId
 
@@ -483,7 +483,7 @@ Standard error response format:
 }
 ```
 
-Google revocation is a first-class error contract used by API and websocket flows:
+Google revocation is a first-class error contract used by API and SSE flows:
 
 ```json
 {

docs/backend/backend-error-handling.md

@@ -54,7 +54,7 @@ Internal details such as stack traces and operational flags stay server-side.
 - Keep `code` stable and machine-oriented. Prefer values like `GOOGLE_ACCOUNT_ALREADY_CONNECTED`.
 - Put technical detail in logs, not in the client payload.
 - Prefer reusing existing feature error metadata before inventing new names.
-- If the error should trigger special auth/sync behavior, verify both API handling and websocket side effects.
+- If the error should trigger special auth/sync behavior, verify both API handling and SSE side effects.
 
 ## Shared Frontend-Backend Error Pattern
 

docs/backend/backend-request-flow.md

@@ -142,7 +142,7 @@ When adding a public contract, prefer creating or extending a shared schema in `
 3. Keep the controller thin: extract params, user id, and response orchestration only.
 4. Put business logic in a service.
 5. Add or update tests at the controller/service level.
-6. If the endpoint affects realtime UI, check whether a websocket notification is also needed.
+6. If the endpoint affects realtime UI, check whether an SSE notification is also needed.
 
 ## Where Bugs Usually Hide
 

docs/development/agent-onboarding.md

@@ -43,9 +43,9 @@ sed -n '1,260p' packages/core/src/types/event.types.ts
 - Event controller: `packages/backend/src/event/controllers/event.controller.ts`
 - Event service: `packages/backend/src/event/services/event.service.ts`
 - Sync service: `packages/backend/src/sync/services/sync.service.ts`
-- Websocket server: `packages/backend/src/servers/websocket/websocket.server.ts`
+- SSE server: `packages/backend/src/servers/sse/sse.server.ts`
 - Shared event types: `packages/core/src/types/event.types.ts`
-- Shared websocket constants: `packages/core/src/constants/websocket.constants.ts`
+- Shared SSE event names: `packages/core/src/constants/sse.constants.ts`
 
 ## If You Are Touching...
 
@@ -56,8 +56,8 @@ sed -n '1,260p' packages/core/src/types/event.types.ts
 - Backend endpoints:
   [Backend Request Flow](../backend/backend-request-flow.md),
   [API Documentation](../backend/api-documentation.md)
-- Google sync or websocket behavior:
-  [Google Sync And Websocket Flow](../features/google-sync-and-websocket-flow.md)
+- Google sync or SSE behavior:
+  [Google Sync And SSE Flow](../features/google-sync-and-sse-flow.md)
 - Local persistence:
   [Offline Storage And Migrations](../features/offline-storage-and-migrations.md)
 - Event or task shape: