04 — Information Architecture (Settings Module)

1. Placement in the app shell
2. Data model: groups (fixed enum)
3. Route table (module-owned; extends 00-shared/05 §4)
4. Screen hierarchy
5. Modal hierarchy (module, per 00-shared/05 §5)
6. Screen relationships & state handoff
7. Cross-surface: embedded org settings (context, not module-owned)
8. Quick actions / FAB / context menus
9. Accessibility of IA

Where the Settings module lives in the shell (00-shared/05 §2: Settings → /settings, role: admin) and how its data surface is organized. Everything derived from setting.schema.ts (groups), settings.controller.ts (API), and the organizations module's separate embedded-settings surface.

1. Placement in the app shell

AppShell
 └─ Settings (nav destination, admin) ─ /settings
     ├─ Settings hub (this module): group tabs + key/value list
     ├─ Roles & permissions   (RBAC module: /settings/roles, /settings/members)
     ├─ Security              (Auth module: /settings/security/*)
     ├─ Organization          (/organization — embedded settings + branding + flags)
     └─ Profile               (avatar menu → /settings/profile)

The module owns only the key/value Settings hub. Sibling surfaces under the same /settings prefix are owned by other modules (see design-docs/rbac/04, design-docs/auth/04).

2. Data model: groups (fixed enum)

Group	Enum value	Typical contents (illustrative; no registry exists)	Source
Academic	`academic`	grading scale, passing %, academic labels	`setting.schema.ts:8`
Attendance	`attendance`	grace period, late threshold, working days	`setting.schema.ts:9`
Grading	`grading`	grade bands, rounding	`setting.schema.ts:10`
Notification	`notification`	channel toggles, digest times	`setting.schema.ts:11`
Theme	`theme`	primary/secondary color (parallels org `settings.theme`)	`setting.schema.ts:12`
General	`general` (default)	anything ungrouped	`setting.schema.ts:13,24-25`
`COACHING`	`(planned)`	batch defaults, test series config, DPP settings	`IMPLEMENTATION_PLAN.md:773`

Server sorts list by group: 1, key: 1 (settings.service.ts:11) — the UI renders tabs in enum order (setting.schema.ts:7-14 declaration order) and rows alphabetically per group.

3. Route table (module-owned; extends `00-shared/05 §4`)

Route	Screen	Auth	Source API
`/settings`	Settings list (hub)	JWT + `settings.read` (client)	`GET /settings[?group=]`
`/settings/group/:group`	Group-filtered list (deep link)	same	`GET /settings?group=`
`/settings/:key`	Setting detail + edit	JWT + `settings.read/update`	`GET /settings/:key`, `PUT /settings`
`/settings/403`	shared permission screen	—	—

4. Screen hierarchy

flowchart TD
    SET[/settings/] --> GRP[/settings/group/attendance/]
    SET --> DET[/settings/:key/]
    DET --> EDIT[typed editor inline]
    SET --> BULK[multi-select → Save all]
    subgraph sibling surfaces (other modules)
      RBAC[/settings/roles/]
      SEC[/settings/security/]
    end

List is the hub; detail is a push (phone) / right pane (tablet+, master-detail ≥840 dp).
Editing happens in place on the list (inline typed editor per row) or on the detail page — both call the same PUT /settings upsert (see 03 §2, 08).

Snackbar/toast — "Saved", "Setting deleted", "Copied (JSON)".
Bottom sheet — JSON editor (multi-line, needs height), delete confirm for inline rows.
Dialog — delete confirm (destructive), "Discard changes?" on dirty exit, JSON parse error details.
Full-screen page — setting detail (key, group, value, meta).
Loader — row-level saving spinner; never full-screen dual column (list is cached).

6. Screen relationships & state handoff

Detail edits return to the list with the row refreshed from the server response (data: Setting from PUT /settings).
Group chip state survives navigation via SettingsCubit (selected group held in state, 13_State_Management.md).
Delete pops detail → list; row removed on server 200 (or 404 treated as removed).

7. Cross-surface: embedded org settings (context, not module-owned)

Surface	Location	Source
Org embedded `settings` (attendance/academic/theme objects)	`/organization` → Settings tabs (Organizations module S4)	`organization.schema.ts:96-112`; `organizations.controller.ts:56-72`
Org branding (colors/logo/favicon)	`/organization` → Branding	`organization.schema.ts:114-120`
Feature flags (boolean toggles)	`/organization` → Feature flags	`feature-flags.controller.ts:23-58`; `feature-flag.schema.ts:9-23`

Design consequence: two surfaces can hold overlapping concepts — settings.theme keys in this module vs organization.settings.theme + branding (dual-surface confusion, see design-docs/organizations/09 § — "Which settings apply?" OQ). The Settings hub must carry a visual note: "Org-level config (attendance, theme, working days) also lives under Organization" with a cross-link, until the blueprint's organization_settings collection (COLLECTIONS.md:767-783) consolidates them (planned).

8. Quick actions / FAB / context menus

FAB (list, extended): "New setting" → creates an unsaved key (group default GENERAL).
Row menu (AppMenu): Edit value, Duplicate key (new key copy), Delete.
Multi-select (long-press rows on phone; checkboxes on desktop) → bottom Save all bar.
Keyboard (desktop): Ctrl+F focuses search (client-side); + / N new setting; Esc closes editor/confirm; Ctrl/Cmd+Enter saves from the JSON editor (00-shared/08 §2).

9. Accessibility of IA

One headlineMedium per screen; group tabs announced as tab list with selected state.
Focus order: search → group chips → first row; row edit opens editor with focus in value.
Group chips never color-only — label + selected pill (00-shared/09 §9).

Keyboard shortcuts

StudyLyon — Design Docs