SwitchbackTech · tyler-dane · Mar 30, 2026 · Mar 30, 2026 · Mar 30, 2026 · Mar 30, 2026
diff --git a/AGENTS.md b/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

diff --git a/docs/README.md b/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)
diff --git a/docs/architecture/event-and-task-domain-model.md b/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.

diff --git a/docs/architecture/glossary.md b/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.
 

diff --git a/docs/architecture/repo-architecture.md b/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
diff --git a/docs/backend/README.md b/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)
diff --git a/docs/backend/api-documentation.md b/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
 {

diff --git a/docs/backend/backend-error-handling.md b/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
 

diff --git a/docs/backend/backend-request-flow.md b/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
 

diff --git a/docs/development/agent-onboarding.md b/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:

diff --git a/docs/development/common-change-recipes.md b/docs/development/common-change-recipes.md
@@ -9,7 +9,7 @@ These are the safest implementation paths for common Compass changes.
 3. Keep the controller thin in `controllers/*.controller.ts`.
 4. Put business logic in `services/*.service.ts`.
 5. Add controller or service tests.
-6. If the endpoint affects realtime UI, decide whether a websocket event is required.
+6. If the endpoint affects realtime UI, decide whether an SSE event is required.
 
 ## Add A New Event Field
 
@@ -45,12 +45,12 @@ Do not edit recurring behavior from one layer only.
 6. Run focused tests:
    - `yarn test:backend --runTestsByPath packages/backend/src/event/classes/compass.event.parser.test.ts packages/backend/src/event/classes/compass.event.executor.test.ts packages/backend/src/sync/services/sync/__tests__/compass.sync.processor.test.ts --runInBand`
 
-## Add A Websocket Event
+## Add An SSE Event
 
-1. Add the event name to `packages/core/src/constants/websocket.constants.ts`.
-2. Update shared websocket types in `packages/core/src/types/websocket.types.ts` if needed.
-3. Emit from `packages/backend/src/servers/websocket/websocket.server.ts`.
-4. Consume it in a web socket hook under `packages/web/src/socket/hooks`.
+1. Add the event name to `packages/core/src/constants/sse.constants.ts`.
+2. Update shared payload types in `packages/core/src/types/sse.types.ts` if needed.
+3. Emit from `packages/backend/src/servers/sse/sse.server.ts` (or call site that uses `publish`).
+4. Consume it in a web hook under `packages/web/src/sse/hooks` (listeners on `EventSource`).
 5. Add tests on both emitter and listener sides.
 
 ## Add Or Change Local Storage Data

diff --git a/docs/development/deploy.md b/docs/development/deploy.md
@@ -48,5 +48,5 @@ node build/node/packages/backend/src/app.js
 Deployment notes:
 
 - backend requires MongoDB, SuperTokens, and Google credentials
-- if you run behind a reverse proxy, it must support websocket upgrades
+- if you run behind a reverse proxy, configure buffering/timeouts for long-lived `text/event-stream` responses (SSE)
 - ngrok is only relevant for local watch/debug flows, not normal hosted deploys
diff --git a/docs/development/env-and-dev-modes.md b/docs/development/env-and-dev-modes.md
@@ -32,7 +32,7 @@ Use this for:
 - authenticated API work
 - Google OAuth/session behavior
 - Mongo-backed event behavior
-- sync and websocket work
+- sync and SSE work
 
 This requires valid env config.
 
@@ -136,7 +136,7 @@ Webpack behavior (`packages/web/webpack.config.mjs`):
 - Google connection flows
 - backend validation behavior
 - Mongo persistence
-- websocket server behavior
+- SSE stream behavior
 
 ## Backend Health Probe
 

diff --git a/docs/development/feature-file-map.md b/docs/development/feature-file-map.md
@@ -73,13 +73,14 @@ Use this document to find the first files to inspect for common Compass changes.
 - Legacy schema migration: `packages/web/src/common/storage/adapter/legacy-primary-key.migration.ts`
 - Data/external migrations: `packages/web/src/common/storage/migrations`
 
-## Sync And Websockets
-
-- Web socket client: `packages/web/src/socket/client/socket.client.ts`
-- Web socket hooks: `packages/web/src/socket/hooks`
-- Web socket provider: `packages/web/src/socket/provider/SocketProvider.tsx`
-- Shared websocket event names: `packages/core/src/constants/websocket.constants.ts`
-- Backend websocket server: `packages/backend/src/servers/websocket/websocket.server.ts`
+## Sync And SSE
+
+- SSE client: `packages/web/src/sse/client/sse.client.ts`
+- SSE hooks: `packages/web/src/sse/hooks`
+- SSE provider: `packages/web/src/sse/provider/SSEProvider.tsx`
+- Shared SSE event names: `packages/core/src/constants/sse.constants.ts`
+- Backend SSE server: `packages/backend/src/servers/sse/sse.server.ts`
+- Events stream route: `packages/backend/src/events/events.routes.config.ts`
 - Backend sync routes/services: `packages/backend/src/sync/sync.routes.config.ts`, `packages/backend/src/sync/services`
 
 ## Users / Metadata / Priority

diff --git a/docs/development/testing-playbook.md b/docs/development/testing-playbook.md
@@ -222,7 +222,7 @@ Useful anchors:
 
 - `packages/web/src/__tests__`
 - `packages/web/src/views/**/*.test.tsx`
-- `packages/web/src/socket/**/*.test.ts`
+- `packages/web/src/sse/**/*.test.tsx`
 
 ## Backend Test Style
 
@@ -267,10 +267,10 @@ Use them for:
 
 ## Testing Realtime And Sync Changes
 
-For websocket or sync work:
+For SSE or sync work:
 
 - test backend emitters/handlers where possible
-- test web socket hooks for listener registration and dispatch behavior
+- test web SSE hooks for listener registration and dispatch behavior
 - test event sagas if refetch or optimistic behavior changed
 
 ## Common Gaps To Watch

diff --git a/docs/development/troubleshoot.md b/docs/development/troubleshoot.md
@@ -56,7 +56,7 @@ To fix this:
 
 When a user triggers repair from the UI (`Repair Google Calendar`) and the flow
 does not complete as expected, first classify the failure mode from the message
-and websocket behavior.
+and SSE behavior.
 
 ### Quota / rate-limit during repair