06 — Screen Specifications (WS / Realtime Module)

• §1 Connection Status Indicator
  • 1.1 Placement & anatomy
  • 1.2 State machine (client)
  • 1.3 Rules
  • 1.4 Source grounding
• §2 Notification Bell + Toast
  • 2.1 Bell badge
  • 2.2 Toast
  • 2.3 Edge cases
• §3 Live-updating Lists & Dashboard Tiles
  • 3.1 The AppLiveList contract
  • 3.2 Per-screen event mapping (proposed defaults; align with each module doc)
  • 3.3 Rules
• §4 Connection Status Detail Sheet (proposed)
• §5 Realtime Admin Debug View /admin/realtime (proposed)
  • 5.1 Layout
  • 5.2 Behavior
  • 5.3 Notes
• §6 Cross-cutting specifications

Detailed specification of every realtime surface from 05. All behavior is tied to source facts where they exist; client-side behavior not in source is marked "(proposed)" or "(planned)". This is the largest spec of the module — it is the contract the Flutter/web client must implement.

§1 Connection Status Indicator

1.1 Placement & anatomy

• Top app bar trailing slot on mobile; app-bar region on desktop; offline state promotes to a full-width AppConnectionBanner under the app bar (see 00-shared/03 for primitives).
• Contains: status dot (8 dp) + optional label "Live" / "Offline — retrying…".

1.2 State machine (client)

1.3 Rules

• Status is global (one app-level state), never per-screen.
• No modal ever blocks on connection state; the layer is passive (see 09).
• Stale-data rule: while offline/reconnecting, any screen showing live-fed values renders the offline banner; values are not cleared (graceful degradation).
• a11y: every state change announces via SemanticsService.liveRegion; dot never color-only (00-shared/09).

1.4 Source grounding

• Auth failure path: missing token → UnauthorizedException('Missing token'), catch → client.disconnect() (ws.gateway.ts:37-40,54-56).
• No server session resumption: reconnect = full re-handshake (see 03 J4).

§2 Notification Bell + Toast

2.1 Bell badge

• Badge counts notification.created events since last list open (client-side count).
• Cap display at 99+.
• On bell open → fetch list via REST (authoritative) and reset count — events are ephemeral; the list is source of truth (bridge is fire-and-forget, ws-bridge.service.ts:16-22).

2.2 Toast

• Shown for notification types marked high-priority (module config, (planned) — the notifications module owns priority semantics, IMPLEMENTATION_PLAN.md:231).
• One toast at a time; queue others; auto-dismiss 5 s; tap → navigate to target route.
• While the user is typing/editing: toast never steals focus (see 10 §2).

2.3 Edge cases

§3 Live-updating Lists & Dashboard Tiles

3.1 The AppLiveList contract

Applies to: Dashboard overview, Fees, Attendance, Homework, Results, CRM lists.

1. Screen subscribes (via RealtimeClient stream, 13) to the event families it renders.
2. On event: match payload.entityId against loaded rows.
   • Hit → update that row in place (m-fast highlight flash).
   • Miss (not loaded or filtered out) → decide by screen rule: if the entity belongs to the current filter, insert; else ignore.
3. If a screen cannot map the payload to a row (schema drift), it schedules one REST refetch of the current page (bounded: 1 refetch / 5 s / screen).
4. Sorting/aggregation (e.g. dashboard totals) → recompute locally, do not refetch.
5. Offline state: keep last known data, banner on; on reconnect → one refetch per visible live screen (eventual consistency, 03 J4 step 5).

3.2 Per-screen event mapping (proposed defaults; align with each module doc)

3.3 Rules

• Live events never replace the primary load; they mutate an existing snapshot.
• Never write user-visible "confetti" or full-screen overlays on events — 09 keeps the layer passive.
• Pull-to-refresh stays available and forces a REST refetch regardless of socket state.

§4 Connection Status Detail Sheet (proposed)

§5 Realtime Admin Debug View /admin/realtime (proposed)

5.1 Layout

• Header: connection state + socket count for this tenant (server-provided — see note), pause/resume toggle, eventType filter chips.
• Body: AppEventLog — monospace rows: time | eventType | payload.size | entityId.
• Footer: session token expiry countdown (client-side check against JWT_ACCESS_SECRET expiry from the auth store).

5.2 Behavior

• Log buffers last 500 events client-side; pause stops render (not capture).
• Filter by eventType substring; clear button.
• Row tap → payload pretty-printed in a bottom sheet.

5.3 Notes

• Client-side only today: it renders what the socket receives. Server-side metrics (per-connection views, room members) are forward-looking — the gateway logs connect/disconnect only (ws.gateway.ts:51-53,59-61).
• Gate with admin role: reuse existing RBAC admin permission (rbac module); no ws.* permission exists yet (permissions.constants.ts:1-97 — verified absent, see 12).

§6 Cross-cutting specifications