Expected behaviours, mistakes, fast paths, persona-class needs, interrupted sessions,
retries, abandonment, frustrations + UX solutions. Derived from code semantics.
Context Expected behaviour Why (source)
Save profile → overview Overview reflects change instantly PATCH returns updated doc (organizations.service.ts:124-126); client reconcilesToggle a feature flag Immediate flip, rollback on failure full-replace map API (organizations.service.ts:144-154) → optimistic per 00-shared/06 §3.5 Change working days Affects future attendance counts only; no retro warning settings replace semantics (:129-137) Delete tenant Row gone immediately; understood as reversible 30 days soft delete (organizations.repository.ts:60-66) + purge worker (tenant-purge.worker.ts:32-42) Create tenant with name "St. Mary's School" Slug auto = st-marys-school slugify (organizations.service.ts:161-169) — user expects predictability; show preview (F1 SlugPreview)Change plan/status Banner/status updates everywhere PATCH $set (:124)
Mistake UX solution
Mistyped slug/domain → 409 Inline field error + suggested alternatives (name-derived slug via SlugPreview) Editing slug late (admins already registered with it) Pre-submit confirm dialog: "Existing admins keep working; new registrations must use the new slug" Saving one settings tab → siblings wiped Full-object save model (S4); dirty-dot per tab; "Save all" only; never per-tab save Toggling flags fast (double-tap) Anti-double-submit on toggle; final state from server reconcile Register with wrong tenant slug (forward-looking) pre-submit hint + "tenant not found" guidance on login failure; server validation (planned) OQ-2Deleting the wrong tenant Typed confirm (type org name) — 00-shared/05 §5 Setting timezone/currency via free text Searchable picker sheets; free text still allowed server-side (@IsString) but discouraged Half-day threshold < late threshold Cross-field validation hint (proposed)
Desktop: N new tenant (S7); Ctrl+K global search; Enter submits forms (M §2).
Overview → any edit surface in 1 tap (toolbar actions); settings deep link from onboarding banner.
Toggle rows don't require save (flags are immediate); settings require explicit "Save all" (destructive-ish).
Tenants list keeps sort/search while paging (debounced q, pagination-query.dto.ts:21-29).
Platform Super Admins batch-provision: support multi-select on list (proposed) and keyboard-driven status change; expect meta.totalItems accuracy after each delete (refetch meta).
First-run: onboarding banner drives them to S4 (academic year + attendance) before other modules.
Invited admin: registration pre-fill from invite context (forward-looking); slug handoff copy in S8 create success.
Keyboard-only desktop flows; expect status change without dialog navigation friction (menu → confirm → done ≤3 steps).
Expect full settings object integrity — Surface "last saved {time}" per tab.
VoiceOver/TalkBack: badge states, toggle results, error focus (A §5, §10); color picker hex fallback; never color-only status.
Keyboard: focus order = toolbar → search → filters → list; ESC closes menus/sheets; typed confirm dialog traps focus (A §6).
Interruption Behaviour
App kill mid-form Form drafts lost (in-memory only) — guidance: save early; (proposed) autosave to prefs Network loss mid-save Pending spinner → error snackbar "Couldn't save — retry" (idempotent PATCH; safe to retry) 401 mid-save Silent refresh → replay; refresh failure → session-expiry overlay, draft preserved (00-shared/06 §3.6 ) Rate limited (429) "Too many requests — retry in Ns", backoff, no auto-retry (07_API_Conventions.md §4 ) 5xx Generic + requestId; retry offered (never surface internals — http-exception.filter.ts:60-64)
Cancel edit → unsaved-guard dialog (Keep editing / Discard); discard = back, no server call (nothing sent until submit).
Tenants list pagination resets on filter change — fine (page 1); note: page beyond totalPages returns empty list (meta still says hasNext:false — pagination-query.dto.ts:46-53) → show "End of results".
Frustration Root cause Solution
"Why is my org missing?" OQ-1 — no self-org endpoint (planned) /organizations/me; stopgap lookup documented; never guess"My settings disappeared" full-replace $set {settings} (organizations.service.ts:134) full-object save model + wipe-prevention QA (S4) "Which settings apply?" dual surfaces: embedded vs settings collection (OQ-6) visual separation + copy on reference tabs "I see other schools!" unscoped list + unguarded controller (OQ-4) platform-only gating client-side; server scope (planned) "Flag toggle didn't stick" full-map replace races (last-write-wins) optimistic + reconcile + pull-to-refresh; WS push (forward-looking) "Delete isn't permanent?" 30-day purge retention explicit snackbar/copy "purged after 30 days"; no restore endpoint (ops-only)