04 — Information Architecture (WS / Realtime Module)

• 1. Transport
• 2. Identity model
• 3. Room model
• 4. Event taxonomy
• 5. Consumer mapping (web UI)
• 6. Naming conventions for the web client

The transport contract of the realtime layer: namespaces, rooms, envelope, naming. Mirrors 00-shared/05 at the wire level; module facts here are all source-grounded.

1. Transport

2. Identity model

A connected socket carries (source ws.gateway.ts:14-18,46-48):

AuthenticatedSocket { userId, tenantId, roles[] }   ← from verified JWT (payload.sub, tenantId, roles)

• Tenant scope is fixed at connect time by the JWT (ws.gateway.ts:47); it is never supplied by the client on the wire. This is the security boundary of the whole module.
• roles[] are carried but unused in routing today (gap; see 12).

3. Room model

Rules:

• subscribe/unsubscribe accept any string (type-checked only: typeof room !== 'string' returns silently — ws.gateway.ts:65,71). No allow-list, no RBAC check → gap (see 12).
• Rooms are per-connection and die with the socket; clients must re-subscribe after every reconnect (13_State_Management.md).
• There is no per-user room in source; user-scoped delivery today = tenant room + client-side filter, or an explicit subscribe to a convention like user:{id} (planned convention, not enforced).

4. Event taxonomy

Server→client events are domain event types relayed by the bridge, wrapped in an envelope (ws-bridge.service.ts:17-21):

{
  "eventType": "notification.created",
  "occurredAt": "2026-08-03T09:00:00.000Z",
  "payload": { }
}

• Names use dot notation — blueprint convention: attendance.updated, payment.completed, notification.created, homework.published (API_STANDARDS.md:642-658).
• The underlying DomainEvent also carries actorId and correlationId (events/domain-event.interface.ts:1-8) — not forwarded by the bridge today.
• Client→server events in source: exactly subscribe and unsubscribe (ws.gateway.ts:63-74).

5. Consumer mapping (web UI)

6. Naming conventions for the web client

• Channel constants in one file (realtime_channels.dart) — mirror server room strings.
• Event constants mirror server eventType strings 1:1 (no client-side renaming).
• Envelope is the only accepted server→client shape; anything else is a protocol violation.