05 — Global Information Architecture (Shared)

• 1. App shell
• 2. Top-level destinations (role-gated)
• 3. Navigation model
• 4. Routing table (shared)
• 5. Modal hierarchy (shared)
• 6. Screen relationships
• 7. Quick actions & FABs
• 8. Cross-cutting screens owned by shared package
• 9. Roles → permission model (client-side)

The app shell, navigation model, routing, and role-based surface mapping that every module slots into. Module docs 04_Information_Architecture.md describe their own screens and where they live in this shell.

1. App shell

MaterialApp
 └─ AppShell (role-aware)
     ├─ NavigationBar (phone) / NavigationRail (tablet+)
     ├─ NavigationDrawer (hamburger, all platforms)
     ├─ AppBar (contextual per screen)
     ├─ Router (go_router, declarative)
     └─ Scaffold body = module pages

• AppShell resolves current role + permissions once at login and on refresh; it drives which destinations and routes are reachable.
• Unauthorized destinations are hidden and unroutable (guard rejects → 403 screen or redirect to home).

2. Top-level destinations (role-gated)

Default landing per role: Student → Home; Teacher → Attendance/Today; Parent → Home; Admin → Dashboard; Accountant → Fees.

3. Navigation model

• Phone (< 600 dp): bottom NavigationBar (max 5 destinations; more via drawer), drawer for the rest, stack navigation with go_router StatefulShellRoute.
• Tablet (600–1199 dp): NavigationRail + master-detail; detail in right pane.
• Desktop (≥ 1200 dp): rail or permanent drawer; master-detail; keyboard nav.
• Nested navigation: module shells use StatefulShellBranch so tab state survives bottom-nav switches.
• Breadcrumbs: desktop only, on detail screens deeper than 2 levels.
• Global search: AppBar search icon → /search (all roles, results scoped).

4. Routing table (shared)

Deep links:

• studylyon://notifications/:id → notification detail (marks read)
• studylyon://homework/:id, studylyon://results/:id, studylyon://messages/thread/:id, studylyon://attendance/:date, studylyon://invoice/:id (module docs enumerate their own)

5. Modal hierarchy (shared)

1. Snackbar/Toast — transient, never blocks.
2. Bottom sheet — pickers, filters, quick actions (half/full height).
3. Dialog — confirmations, forms ≤ 3 fields, destructive confirms.
4. Full-screen page — forms with > 3 fields, detail screens, wizards.
5. Loader — only when nothing else can render (skeletons preferred).

Rule: destructive actions need explicit dialog confirm; irreversible server-side ops (double-delete, purge) need typed confirm (AppDialog + text input of entity name).

6. Screen relationships

• List → Detail → Edit/Form; Edit returns → Detail (refresh); Detail → related lists (e.g., Student → Attendance, Fees, Results) via tabs.
• Master-detail on tablet/desktop; push-on-top on phone.
• Context menus on list rows for quick actions (edit, duplicate, delete, more).

7. Quick actions & FABs

• One FAB per screen, module-defined (e.g., Students → "Add student", Attendance → "Mark today").
• Context menus (AppMenu) for row actions; swipe actions on phone for common ops (mark read, delete draft, archive).
• Keyboard: desktop Ctrl+K → global search; Esc closes modal/sheet; + or N new on list screens (documented per module).

8. Cross-cutting screens owned by shared package

• 403 Permission screen, 404 Not Found, 500 Error screen, Offline screen
• Session expiry overlay (silent refresh failed) → re-login
• Global search results shell
• Notification center shell
• Account/profile (self-service): avatar menu → profile, password, 2FA, devices, preferences

9. Roles → permission model (client-side)

• Client mirrors permissions.constants.ts; route guards check user.permissions.contains('x.y').
• Server remains authoritative: client 403/404 handling matches server error codes (PERMISSION_DENIED, RESOURCE_NOT_FOUND).
• Custom roles: permission sets resolve per tenant; client rebuilds routes on role change.