# SSE Realtime Design

## Goal

Replace HTTP polling (`refetchInterval: 45_000`) with Server-Sent Events (SSE) for real-time updates: chat messages, unread counters, order status changes, admin notifications.

## Decisions

| Decision | Choice | Rationale |
|---|---|---|
| Technology | SSE over WebSocket | Native browser API, auto-reconnect, simpler server code. Messages still sent via HTTP POST. |
| SSE approach | Direct EventBus bridge (no recovery buffer) | Sufficient for shop scale. EventSource has built-in auto-reconnect. |
| Connection lifecycle | Connect on login, close on logout | SSE created when JWT appears in Effector `$token`, closed on `null`. |
| Auth method | JWT in query param (`?token=`) | EventSource doesn't support custom headers. Server's `authenticate` decorator already handles `request.query?.token`. |

## Server-side

### New file: `server/src/routes/sse.js`

Single SSE endpoint:

```
GET /api/sse/stream?token=JWT
PreHandler: fastify.authenticate
```

**Behavior:**
1. Sets SSE headers: `Content-Type: text/event-stream`, `Cache-Control: no-cache`, `Connection: keep-alive`.
2. Sends heartbit comment every 30s: `:heartbit\n\n` (invisible to EventSource, keeps connection alive).
3. Subscribes to `request.server.eventBus`, filters events by user identity, pushes matching events through SSE.
4. On `response.raw.on('close')` — removes EventBus listeners.

**Event mapping (EventBus → SSE):**

| EventBus event | Who receives | SSE `event` type | Payload |
|---|---|---|---|
| `orderMessage:adminReply` | User (order.userId) | `message:new` | `{ orderId, messageId, preview }` |
| `order:statusChanged` | User (order.userId) | `order:statusChanged` | `{ orderId, newStatus }` |
| `payment:statusChanged` | User (order.userId) | `order:statusChanged` | `{ orderId, paymentStatus }` |
| `order:deliveryFeeAdjusted` | User (order.userId) | `order:updated` | `{ orderId }` |
| `orderMessage:sent` | Admin (all admins) | `message:new` | `{ orderId, messageId, preview }` |
| `order:created` | Admin | `order:new` | `{ orderId }` |

**Admin filtering:** If `request.user` is admin (checked via email match), subscribe to all admin events without userId filtering. Currently only one admin exists, so this is straightforward.

### Modified file: `server/src/index.js`

Add import and registration:

```js
import { registerSseRoutes } from './routes/sse.js'
// ...
await registerSseRoutes(fastify)
```

No other server changes needed. Existing `authenticate` decorator (line 75-84) already supports `request.query?.token`.

## Client-side

### New file: `client/src/shared/lib/sse.ts`

Factory function:

```ts
export function createEventStream(token: string): EventSource {
  return new EventSource(`/api/sse/stream?token=${encodeURIComponent(token)}`)
}
```

### New file: `client/src/app/providers/SseProvider.tsx`

React component that bridges SSE events to React Query cache invalidation:

1. Subscribes to `$token` from Effector (`@/shared/model/auth`).
2. When token appears → creates `EventSource` via `createEventStream(token)`.
3. When token becomes `null` → closes `EventSource`.
4. Registers `onmessage` handlers for each SSE event type:

| SSE event | Handler |
|---|---|
| `message:new` | User side: `invalidateQueries(['me', 'messages', 'unread-count'])`, `invalidateQueries(['me', 'conversations'])`, `invalidateQueries(['me', 'orders', orderId])`. Admin side: `invalidateQueries(['admin', 'orders', orderId])`. |
| `order:statusChanged` | `invalidateQueries(['me', 'orders', orderId])`. Admin (if viewing): `invalidateQueries(['admin', 'orders', orderId])`. |
| `order:new` | Admin: `invalidateQueries(['admin', 'orders', 'summary'])`, `invalidateQueries(['admin', 'orders'])`. |
| `order:updated` | `invalidateQueries(['me', 'orders', orderId])`. Admin (if viewing): `invalidateQueries(['admin', 'orders', orderId])`. |

React Query's `invalidateQueries` only refetches active (currently mounted) queries. Inactive queries are just marked stale. This means SseProvider can call `invalidateQueries(['me', 'orders', orderId])` unconditionally — it will only refetch if the user has that order's chat page open.

5. Uses `useQueryClient()` to access the query client.

### Modified files

**`client/src/app/providers/AppProviders.tsx`:**
- Add `<SseProvider>` as a child of `QueryClientProvider` (or wrap it around, needs `queryClient`).

**`client/src/pages/me/ui/MeLayoutPage.tsx`:**
- Remove `refetchInterval: 45_000` from the unread count query.
- Remove `refetchOnWindowFocus: true` (revert to global default `false`).

**`client/src/pages/admin-layout/ui/AdminLayoutPage.tsx`:**
- Remove `refetchInterval: 45_000` from the orders summary query.
- Remove `refetchOnWindowFocus: true` (revert to global default `false`).

## Data Flow (example: admin replies to user)

```
Admin → POST /api/admin/orders/:id/messages
  → Prisma: creates OrderMessage
  → EventBus: emit('orderMessage:adminReply', { orderId, userId, messageId, preview })
  → dispatchNotification: email/telegram to user (existing behavior, unchanged)
  → SSE handler: filters by userId, formats as SSE event

Client (SseProvider):
  → SSE event 'message:new' received
  → invalidateQueries(['me', 'messages', 'unread-count'])   → badge updates
  → invalidateQueries(['me', 'conversations'])              → dialog list updates
  → invalidateQueries(['me', 'orders', orderId])            → chat updates (only if that order's query is active)
```

## Files Summary

| File | Status | Description |
|---|---|---|
| `server/src/routes/sse.js` | New | SSE endpoint, EventBus→SSE bridge |
| `server/src/index.js` | Modify | Import and register SSE routes |
| `client/src/shared/lib/sse.ts` | New | EventSource factory |
| `client/src/app/providers/SseProvider.tsx` | New | SSE→ReactQuery bridge component |
| `client/src/app/providers/AppProviders.tsx` | Modify | Mount SseProvider |
| `client/src/pages/me/ui/MeLayoutPage.tsx` | Modify | Remove refetchInterval |
| `client/src/pages/admin-layout/ui/AdminLayoutPage.tsx` | Modify | Remove refetchInterval |

## Testing

**Server (vitest):**
- SSE endpoint returns correct headers (`text/event-stream`, `no-cache`, `keep-alive`).
- SSE endpoint sends heartbit comment on connect.
- When EventBus emits an event relevant to the connected user, SSE stream contains the formatted event.
- When EventBus emits an event for a different user, SSE stream does NOT receive it.
- EventSource cleanup: listeners removed on response close.
- Admin receives all admin events regardless of userId.

**Client (vitest + jsdom):**
- `createEventStream(token)` returns EventSource with correct URL including token.
- `SseProvider` creates EventSource when `$token` is set.
- `SseProvider` closes EventSource when `$token` becomes null.
- `SseProvider` calls `queryClient.invalidateQueries` with correct keys on each SSE event type.
- No EventSource created when `$token` is null.