Realtime - API Reference

Audience: Frontend engineers, mobile engineers, backend engineers, QA, and API consumers. Scope: The admin-facing live event stream and its catalogue. For the personal notification stream and push devices, see /docs/developer/notification/api.

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

Both routes are declared with no NestJS version segment; the runtime path is /api/admin/realtime/..., matching every other route in this codebase.

5. Auth, Identity, and Permissions

Why the browser cannot open this route directly. EventSource cannot set an Authorization header. The intended caller is the admin panel's own server (a Next.js route handler acting as a BFF), which holds the session cookie, opens this route server-to-server with an ordinary Authorization: Bearer, and streams the bytes to the browser unmodified. See the client guide for the exact proxy behavior.

Permission resolution timing. The stream route resolves the caller's full permission set once, at connect (RoleService.getPermissionsForRoleId), and holds it for the life of the connection. A permission grant or revocation takes effect on the client's next reconnect, not mid-stream. Two things force that reconnect: removing a role from a staff member ends their open streams through the close-user control message, and a stream whose session's active role changed between authentication and registration is ended as soon as it registers. A change to a role's own permissions on the Roles screen does neither.

6. DTO and Model Reference

6.1 RealtimeCatalogueResponseDto

6.2 RealtimeEventKindDto (nested in kinds[])

6.3 RealtimeEvent (the SSE frame payload, not a DTO class)

8.1 GET /api/admin/realtime/catalogue

Purpose

Every event kind the stream can emit, its sound class, and the permission that gates it — so the admin panel's notification-preferences screen renders from this list instead of a second, hard-coded copy that would drift the moment an event is added or removed.

Source Evidence

Auth and Permissions

JWT, JwtAuthGuard + RoleGuard, permission System_READ. Rate-limited by IpThrottlerGuard at RATE_LIMITS.ADMIN_READ.

Request

Headers only — Authorization. No params, query, or body.

Response

200.

{
  "message": "Realtime catalogue fetched successfully",
  "data": {
    "soundClasses": ["positive", "urgent", "soft", "neutral"],
    "kinds": [
      { "kind": "feedback.submitted", "soundClass": "soft", "permission": "Feedback_READ" },
      { "kind": "exam.published", "soundClass": "neutral", "permission": "Exams_READ" },
      { "kind": "exam.result_published", "soundClass": "positive", "permission": "ExamResults_READ" },
      { "kind": "exam.marks_submitted", "soundClass": "soft", "permission": "ExamMarksVerify_READ" }
    ]
  },
  "errorCode": null
}

Side Effects

None. A pure read of an in-process constant.

Error Cases

Edge Cases

• The list changes only when a code change adds or removes an entry in REALTIME_EVENT_MAP — there is no admin-editable configuration behind it.
• A permission listed here is guaranteed to exist in the permission catalogue at compile time, because RealtimeEventDefinition.permission is typed as PermissionCode.

Example Requests

curl -s "$API_URL/api/admin/realtime/catalogue" -H "Authorization: Bearer TOKEN"

8.2 GET /api/admin/realtime/stream

Purpose

Long-lived text/event-stream of admin notifications. One connection serves every event kind the caller is permitted to see; the server filters per subscriber rather than exposing a stream per permission.

Source Evidence

Auth and Permissions

JWT, JwtAuthGuard + RoleGuard. No @Permissions() — reachable by any authenticated admin with an active role. Every individual event is then filtered against that admin's resolved permissions (or bypassed entirely for superadmin). Intended to be opened server-to-server by the admin panel's own BFF; see the client guide.

Request

Response

200, Content-Type: text/event-stream; charset=utf-8, held open indefinitely. Response headers also include Cache-Control: no-cache, no-transform, Connection: keep-alive, and X-Accel-Buffering: no (defeats nginx's default proxy buffering, which would otherwise hold every event until its buffer fills).

The stream opens with retry: 3000 (how long EventSource waits before its own automatic reconnect), then frames of these types:

A : comment line (: keep-alive <ISO timestamp>) is written every 20 seconds. It is not a frame — EventSource never surfaces comment lines to application code — and exists only to keep idle-connection-reaping proxies from closing the stream.

Side Effects

None durable from the request itself. Registers an in-memory listener and closer on this API instance for the life of the connection — the closer also indexed by the caller's user id, so a close-user control message can find it — and removes them on disconnect. Right after registering, reads the session's active_role_id once.

Error Cases

Once the stream is open, no further HTTP error is possible on this connection — a mid-stream problem (slow consumer, shutdown, transport error, a role change) ends the response instead of returning an error status, because the response has already committed to 200.

Edge Cases

• No cap on concurrent connections per admin. Unlike the personal notification stream (capped at 5 with eviction), this route has no per-user connection limit in the current code.
• Slow consumer. If more than REALTIME_MAX_BUFFERED_BYTES (1 MiB) is queued in the socket, the connection is closed server-side. The client's EventSource reconnects automatically after retry: 3000 ms; Last-Event-ID on that reconnect fills the gap from the 500-event history buffer.
• Server shutdown. An in-flight connection is ended immediately as a normal 200 close (never a non-200, which would make EventSource give up permanently) when the process is draining for a deploy. The client reconnects against the replacement instance.
• Role removed. When a staff role edit removes a role from the caller, every open stream of theirs, on every API instance, is ended through the close-user control message. The client reconnects after retry: 3000 ms with the permissions the session holds now. If the session was acting as the removed role, its active role is gone and the reconnect is refused with 403 PERMISSION_USER_CONTEXT_MISSING until it chooses a role; a client should send the user to the role picker rather than retry. If Redis is unreachable when the role is removed, the close is lost and logged, and the stream keeps its old filter until it next reconnects.
• Active role changed while connecting. The session's active role is read again after the stream registers. If it is no longer the role whose permissions the stream resolved — removed, or switched in another tab — the stream is ended at once, and the client reconnects under the current role.
• Duplicate delivery is possible. The listener is registered before the replay read runs, so an event published in that narrow window can arrive once as a live event frame and once in the replay. Clients must de-duplicate on id.
• History is bounded. A client away longer than 500 events (across the whole deployment, not per-user) receives only what remains in the buffer on reconnect, with no signal that more was missed. Reconcile against the underlying screens, not against the stream, for anything older.
• Reconnecting with a very old Last-Event-ID (older than everything in the 500-event buffer) is treated the same as no filtering being possible — everything still in the buffer that the permission filter allows is replayed as missed.

Example Requests

curl -N "$API_URL/api/admin/realtime/stream" \
  -H "Authorization: Bearer TOKEN" \
  -H "Accept: text/event-stream"

# Reconnecting after having last seen id 4821:
curl -N "$API_URL/api/admin/realtime/stream" \
  -H "Authorization: Bearer TOKEN" \
  -H "Accept: text/event-stream" \
  -H "Last-Event-ID: 4821"

Example raw frames as written to the wire:

retry: 3000

event: ready
data: {"at":"2026-09-24T06:00:00.000Z"}

event: history
id: 4820
data: {"id":4820,"kind":"feedback.submitted","soundClass":"soft","permission":"Feedback_READ","aggregateId":"0192f900-aaaa-7a10-b3d2-6f1e0c5a7b50","occurredAt":"2026-09-24T05:58:12.000Z","summary":"New contact message (support)"}

: keep-alive 2026-09-24T06:00:20.000Z

event: event
id: 4822
data: {"id":4822,"kind":"exam.result_published","soundClass":"positive","permission":"ExamResults_READ","aggregateId":"0192f900-bbbb-...","occurredAt":"2026-09-24T06:00:25.000Z","summary":"exam.result_published"}

9. Validation and Constraints Summary

10. Integration Checklist

• The stream is opened server-to-server (BFF pattern), never directly from a browser EventSource, because the browser cannot set Authorization.
• Last-Event-ID is forwarded on every reconnect the transport layer performs.
• history and missed frames are rendered as already-read (no toast, no sound); only event frames play a sound, chosen by soundClass.
• The client de-duplicates on id in case of a redelivery-driven duplicate.
• A 403 PERMISSION_USER_CONTEXT_MISSING is treated as "select a role," not retried blindly.
• A stream ended by the server is reconnected, and a reconnect refused with 403 PERMISSION_USER_CONTEXT_MISSING — for example because the session's active role was removed — sends the user to the role picker.
• The panel remains fully correct if the stream never connects — it is an enhancement layered on data the ordinary read routes already serve.

See Also

• Backend doc: /docs/developer/realtime/backend
• Features and flows doc: /docs/developer/realtime/feature
• Client guide: /docs/developer/architecture/live-updates-and-push
• Personal notification stream and push devices: /docs/developer/notification/api