Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

09 — User Behaviour (Parents Module)

Expected behaviour (derived from server semantics + shared interaction rules), common mistakes users make, and UX countermeasures. Purpose: playbook for the UI designer so the flow never surprises.

1. Expected behaviour (server-contract-driven)

  • A guardian profile belongs to one user, forever. tenantId+userId unique index (parent.schema.ts:36); a second profile for the same user → 409. UI must pre-check via the user picker ("this user already has a guardian profile").
  • The same person can be linked to many children and each child can have many guardians (M2M, student-parent-link.schema.ts:18-25) — no "one parent one child" assumptions anywhere in the UI.
  • The profile is identity-light: name/email/phone come from users (parent.schema.ts:8-32, COLLECTIONS.md §2.2). UI never offers to edit name/email in the parent form.
  • pickupAllowed (link) defaults true; pickupAuthorization (profile) defaults false (student-parent-link.schema.ts:33-34, parent.schema.ts:27-28) — UI must present them as separate concerns ("authorized at office level" vs "allowed per child") and not assume they match.
  • Unlink is safe by design: deleting a link never deletes the parent (04-Modules/Parents.md:58); the parent row persists with zero links.
  • Delete is soft: DELETE /parents/:id sets isDeleted (base.repository.ts:68-74); lists exclude it (base.repository.ts:26-28). No hard delete in the API.
  • Audit trail exists: ParentUpdated/ParentDeleted → audit-write jobs (event-queue-map.ts:38-39) — every profile change is traceable.

2. Common mistakes & countermeasures

MistakeRelatedUX countermeasure
Creating a duplicate profile for the same usercreateuser picker warns when the chosen user already has a profile (409 otherwise, parent.service.ts:32-34)
Linking the same guardian to the same child twicelinkclient pre-check over loaded links + warning (server allows duplicates, OQ-2)
Setting two primary guardians for one childlinkwarning when toggling primary while another exists (OQ-5)
Unlinking the primary guardian by accidentunlinkdialog warning "child will have no primary guardian" + confirm (OQ-4)
Typing an invalid relationship valuelinkdropdown only, enum values (student-parent-link.schema.ts:7-14); free text would 500 (OQ-6)
Searching the parents list expecting server searchlistq is ignored server-side (parent.service.ts:58-61) → client-side filter only, or hide search (OQ-7)
Expecting userId to be editableeditno userId in UpdateParentDto (update-parent.dto.ts:4-34) — field hidden, doc note "transfer ownership = create new + link"
Expecting per-child flags editable after linklinkno link PATCH endpoint — per-child flags are set at create only; change = unlink + relink (OQ-4). UI must offer "recreate link" flow with copy preserved
Deleting a parent expecting links to vanishdeletesoft delete leaves links (parent.service.ts:89-100) — UI copy: "Links are kept; children will show the guardian as inactive" (or propose cascade)

3. Power & new users

  • Power user (admission staff): bulk season — keyboard N new guardian, fast user picker, tab-complete student admission numbers; link sheet remembers last relationship per user (session preference, client-side).
  • New user (admin): first-run — empty list → AppEmptyState action "Add guardian"; tooltip "create the user first (Users → Add), then attach the guardian profile".

4. Mobile & a11y users

  • One-thumb phone: single primary CTA per screen; 48 dp targets; switches ≥ 48 row.
  • TalkBack/VoiceOver: link sheet fully walkable; chips announce relationship; switcher announces selected child (09_Accessibility_Baseline.md §7).
  • Dynamic type 200%: child cards reflow; EmergencyFlagsRow wraps; no fixed widths.
  • Reduced motion: no stagger on lists; error = color+icon+text.

5. Interrupted sessions & retries

  • App killed mid-link: sheet state lost; parent/student context retained by route — re-open sheet with preselected context.
  • Mid-submit network loss: CTA stays pending; on reconnect user must retap (no silent auto-retry — write is not idempotent, OQ-2 duplicates possible).
  • 5xx after submit: generic error + requestId; form state preserved; no double row.
  • Offline: lists from last-good cache + banner; all writes blocked.

6. Abandonment

  • Create form abandoned mid-way: nothing saved; user picker selection lost (server has no drafts).
  • Link sheet abandoned: nothing saved — no partial links (link create is atomic).
  • Unlink dialog abandoned: nothing happens (soft-delete only on confirm).

7. Frustration points → UX treatments (summary)

FrustrationTreatment
"Which child does this guardian belong to?"detail groups children with relationship chips + primary badge at a glance
"Why can't I change the relationship after linking?"recreate-link flow in menu with prefilled values; explanatory snackbar
"The guardian shows twice for the same child"duplicate link (server allows) → surface a "Merge/remove duplicate" action that unlinks extras
"No primary guardian!"primary warning on unlink + empty-state hint on student guardian list
"This child's data looks wrong"cross-tenant reads impossible (base.repository.ts:20-30) — any wrongness is a bug, not UI

8. Cross-device & conflict

  • Two admins edit the same parent concurrently → last-write-wins with version bump (base.repository.ts:62-65); no conflict signal to client — UI treats PATCH as absolute (server returned doc is truth).
  • Unlink on one device while another shows the child → next refresh hides it; 404 on delete → treat-as-removed (student-parent-link.service.ts:40).

9. Adoption path (holistic)

  • P0: admin CRUD + link/unlink + primary badge (all server-supported today).
  • P1 (forward-looking): parent self-service (my children, child switcher, my profile) — blocked on my-profile endpoint (OQ-1).
  • P2 (planned): RBAC parent.* permissions (04-Modules/Parents.md:64-70), duplicate link prevention, unique primary enforcement, link PATCH endpoint, cascade policies.