---
name: realtime-feature
description: Live updates over SignalR (.NET) or WebSocket (NestJS) — presence, notifications, collaborative state.
---

# Blueprint: Realtime Feature

## Frontend

- Service wraps the connection; exposes a signal of the latest state.
- Reconnects with exponential backoff; resyncs state on reconnect (snapshot + then delta).

## Backend

- Host choice: SignalR (.NET) when the data lives in the .NET API; NestJS WebSocket gateway when it's queue-driven.
- Authenticate the handshake (Bearer); scope subscriptions by `tenantId` + permission.

## Database

- N/A (in-memory + Redis backplane for horizontal scale).

## API contract

- Message envelope in `packages/api-contracts/src/zod/realtime.ts`: `{ type, version, payload, occurredAt }`.

## UI

- Visible "live" indicator + a "reconnecting…" affordance.
- Coalesce high-frequency updates to avoid render thrash.

## Validation

- Server: validate every incoming client message (Zod).
- Reject messages outside the user's tenant scope.

## Testing

- Two clients receive an update; reconnect resyncs; auth required on handshake.

## Observability

- Connection count gauge; message rate; backpressure events.

## Security

- Auth on handshake — no "anonymous then upgrade".
- Never broadcast cross-tenant.
- Rate-limit per-connection.
