09 — User Behaviour (WS / Realtime Module)
- 1. Users are passive consumers
- 2. Tolerance windows
- 3. Notification consumption
- 4. Editing vs. live mutation conflict
- 5. Admin/debug behaviour (proposed)
- 6. Multi-device reality
- 7. Connection-affecting behaviours
- 8. Trust rules
How users actually interact with a passive realtime layer — and the behavioural rules the client must encode so the module stays invisible until it must be visible. Personas: 02; journeys: 03.
1. Users are passive consumers
- The only explicit user actions tied to realtime: pull-to-refresh (reconciliation),
tapping a toast, opening the status sheet
(proposed), and — offline — tapping "Retry now". Everything else is ambient. - Consequence: no screen may be designed around realtime being present. Every surface must be fully functional with the socket dead (REST fallback). Realtime is an enhancement layer, never a dependency for rendering.
2. Tolerance windows
| Behaviour | Observed pattern | Rule |
|---|---|---|
| Brief reconnect (≤ 5 s) | users don't notice | no banner needed until first retry fails |
| Sustained offline (> 10 s) | users expect an indicator and a path to fix | banner + status sheet |
| Stale numbers | users distrust the screen and reload | offline banner must say updates are paused (06 §1.3) |
| Missed event while offline | users notice only when list looks wrong | reconcile on reconnect (06 §3.1) |
3. Notification consumption
- Users acknowledge toasts within seconds or ignore them entirely; bell badge is the durable signal. Badge reset on bell-open is mandatory (not on toast display).
- Duplicate toasts (multi-tab) are actively confusing — dedupe is a correctness rule (06 §2.3), not polish.
4. Editing vs. live mutation conflict
- A user mid-edit (typing a fee entry, editing a mark) reacts badly to rows re-ordering
or inputs changing underneath them.
AppLiveListmust defer mutation while the screen has an active edit session (10 §2). - Users do not expect their in-progress edits to be merged with live data — deferring the event-driven update until the edit ends is acceptable and expected.
5. Admin/debug behaviour (proposed)
- IT admins open the debug view after deploys and during incident reports; they expect a pauseable stream and filter, not a wall of text. They will screenshot it — payloads must be redactable (no PII in payload render, 10 §8).
6. Multi-device reality
- Same user, two tabs / two devices: both receive tenant broadcasts
(
ws.gateway.ts:50,76-78). Users accept this; they do not accept double toasts — dedupe again. They also expect the last-activity device to win for write conflicts — server-side REST semantics already handle that; realtime never performs writes.
7. Connection-affecting behaviours
- Locking the workstation / closing the laptop → heartbeat timeout → reconnect cycle; users expect zero-state loss on return (state restored, one refetch).
- Background tabs: browsers throttle timers; socket.io ping may stretch — clients should not treat slow pings as failure (use the server's disconnect as the signal, 03 J4).
- Corporate proxies that block WS: engine.io falls back to long-polling (socket.io default transports) — the client must keep functioning in degraded transport.