mralexsaavedra/spotiarr/spotiarr-sse

Activation Contract

Load when adding real-time updates, emitting new SSE events, or extending useServerEvents.

Hard Rules

• Frontend: one SSE connection only — via useServerEvents (hooks/useServerEvents.ts). Never open additional EventSource instances.
• useServerEvents reacts to events by invalidating TanStack Query caches — NOT by writing to Zustand stores.
• No reconnection logic exists — if needed, add it inside useServerEvents, nowhere else.
• Backend: emit SSE events via infrastructure/messaging/app-event-bus.ts only. Never emit from controllers directly.
• useServerEvents must stay mounted inside the authenticated subtree under <TokenGate> (currently AuthenticatedApp in App.tsx). The /api/events SSE endpoint is gated by require-token; mounting SSE before unlock produces 401s. Never hoist useServerEvents above <TokenGate>.

Event Contracts

Adding a New SSE Event

1. Backend: emit via app-event-bus.ts with a new event name string
2. Frontend: add a listener in useServerEvents.ts, invalidate the relevant query keys from queryKeys.ts
3. Shared: if the event payload needs a typed shape, add it to packages/shared/src/index.ts

References

• Frontend hook: apps/frontend/src/hooks/useServerEvents.ts
• Query keys: apps/frontend/src/hooks/queryKeys.ts
• Backend bus: apps/backend/src/infrastructure/messaging/app-event-bus.ts
• Backend controller: apps/backend/src/presentation/controllers/events.controller.ts
• Backend route: apps/backend/src/presentation/routes/events.routes.ts