01 — Product Overview (Shared Platform)

• 1. Purpose
• 2. Business goals
• 3. User goals (top level; per-role detail in each module's 02)
• 4. Stakeholders
• 5. Why this exists
• 6. Platform dependencies (backend)
• 7. Success metrics (platform)
• 8. Global edge cases
• 9. Global assumptions
• 10. Glossary

StudyLyon — Multi-Tenant ERP & School Management Platform. This is the shared foundation document referenced by every module design package.

1. Purpose

StudyLyon is a production-grade, multi-tenant SaaS platform that lets educational institutions (K-12 schools, colleges, coaching centers, training institutes) manage their full operational lifecycle: admissions, academics, attendance, assessments, finance, communication, transport, and library — from a single codebase.

This design-docs collection specifies the client application (Flutter, forward-looking) against the existing NestJS API. The backend is the source of truth for all features, routes, permissions, and data contracts.

2. Business goals

3. User goals (top level; per-role detail in each module's 02)

• Super Admin (platform): onboard institutions, monitor platform health, never touch tenant data.
• Org Admin: run the institution from one dashboard; configure everything; invite staff.
• Teacher: mark attendance, set homework, enter marks with minimal taps; mobile-friendly.
• Accountant: invoices, payments, dues, financial reports; no academic write access.
• Staff/Receptionist: manage profiles, support admin workflows, read across modules.
• Parent: track child's attendance, results, fees, and alerts proactively.
• Student: clear, simple views of homework, results, attendance, fees.
• Ops roles (Transport Manager, Librarian, HR, Principal): run their domain module.

4. Stakeholders

Platform operator (SaaS vendor), institution administrators, teaching staff, non-teaching staff, parents/guardians, students, system actors (notification engine, BullMQ workers, audit logger, webhook consumer), and the engineering/design/QA teams consuming these docs.

5. Why this exists

Institutions run fragmented tooling (paper registers, manual ledgers, physical notices, ad-hoc WhatsApp groups). StudyLyon consolidates these into one tenant-isolated platform with real-time visibility for every stakeholder. The client docs exist because the Phase 3 roadmap calls for a mobile companion; these documents are written to the full API surface so the client can grow to full parity.

6. Platform dependencies (backend)

• Node 24, NestJS 11, strict TypeScript
• MongoDB + Mongoose (shared DB, per-tenant isolation via tenantId)
• Redis: cache (sl:{tenantId}:{key}), rate limiting, BullMQ broker
• BullMQ queues: emails, push, whatsapp, in-app, attendance-process, biometric-sync, invoice-generate, payment-reminder, report-generate, audit-write, tenant-purge, cache-rebuild, webhook-deliver, admission-reminder, admission-expiry
• Storage: STORAGE_PROVIDER interface — Appwrite (Phase 1), Cloudflare R2 (Phase 2), local dev
• WebSockets: WsModule gateway for realtime delivery
• Email (SMTP), push (FCM), WhatsApp (planned)

7. Success metrics (platform)

• Tenant onboarding < 15 min
• Attendance marking latency < 1 s
• Notification delivery P95 < 30 s
• API P95 latency < 200 ms
• 99.9% uptime; zero-downtime deploys
• 100% RBAC enforcement; audit trail on every CUD action

8. Global edge cases

• Tenant isolation violations (cross-tenant ID access) → 403/404, never leak
• JWT expiry mid-session → silent refresh, re-auth on failure
• Offline operation → cached reads, queued writes with idempotency
• Concurrent updates → optimistic lock (version field), 409/422 conflict
• Soft-deleted records never appear in lists
• Rate limiting (429) on auth + API tiers
• Large lists (>100 rows) → pagination, not infinite scroll alone
• Notification fan-out failures → retry + DLQ, user sees "pending" not "failed"

9. Global assumptions

• PRD conflict (flagged): PRODUCT_REQUIREMENTS_DOCUMENT.md:144 puts native mobile apps out of Phase 1 scope; roadmap Phase 3 plans a read-only companion. Decision made with the product owner: these docs specify a full-featured Flutter client now, to the complete API surface. Any conflict with the web-first roadmap is resolved in favor of these docs unless the roadmap is amended.
• No UI design system exists in the repo → Material 3 tokens in 02_Design_Tokens.md are proposed defaults, marked as such, until a designer finalizes them.
• No device/push-token registry exists → push-related flows are forward-looking, flagged.
• Client architecture (Bloc/Cubit) is a recommendation, not an implemented decision.
• API endpoints marked "planned" come from docs/IMPLEMENTATION_PLAN.md and may not be in code yet; they are flagged (planned) in every doc.

10. Glossary

02 — Design Tokens (Shared)

• 1. Color system
  • 1.1 Chromatic roles (light)
  • 1.2 Surface scale (light)
  • 1.3 Outline & inverse
  • 1.4 Dark mode
  • 1.5 Tenant branding
  • 1.6 Raw named palette (designer reference)
• 2. Typography
  • 2.1 M3 type scale mapping
  • 2.2 Non-M3 typography tokens (designer-provided)
• 3. Spacing
  • 3.1 Semantic scale (designer-provided)
  • 3.2 Fixed numeric scale (designer-provided)
  • 3.3 Layout conventions (from previous proposal, mapped to new scale)
• 4. Radius
• 5. Elevation & shadow
• 6. Motion
• 7. Iconography
• 8. Breakpoints (responsive)
• 9. Touch targets
• 10. Light/dark parity rules

STATUS: v1 — designer-provided (Material 3 token export from Figma). Rows marked TBD by designer or (extrapolated…) are not sourced from the export and need designer sign-off before shipping. All module docs reference this file; changes here propagate everywhere.

1. Color system

1.1 Chromatic roles (light)

Designer-provided M3 roles plus two custom extended roles (success, warning — not standard M3, present in the token set).

Note: success and warning are standalone roles, not aliases of secondary/tertiary (previous proposal). Dues/warnings that were formerly tertiary now map to warning; paid/healthy states map to success.

1.2 Surface scale (light)

1.3 Outline & inverse

1.4 Dark mode

Designer-provided dark surface scale (grey/azure family):

• Dark chromatic roles (primary/secondary/tertiary/error/success/warning + containers) are NOT in the export — TBD by designer.
• Working proposal until then (per M3 convention, dark primary ≈ inversePrimary): dark primary ≈ #B7C4FF (Melrose) with onPrimary ≈ #0037B0-family dark. Do not ship dark mode until confirmed.

1.5 Tenant branding

Org branding.color overrides primary only; all other roles stay from this palette. Dark mode default: follow system; org branding can pin one.

1.6 Raw named palette (designer reference)

2. Typography

Font families: Inter (UI) and JetBrains Mono (data/identifiers). Both designer-provided.

2.1 M3 type scale mapping

Rows marked (extrapolated…) were not present as named tokens in the export; they are filled from the nearest fontSize scale steps or adjacent tiers per standard M3 conventions. TBD by designer — confirm before shipping.

2.2 Non-M3 typography tokens (designer-provided)

Usage: mono for IDs, roll numbers, amounts, keys. Numerals (scores, amounts) use FontFeature.tabularFigures().

3. Spacing

3.1 Semantic scale (designer-provided)

3.2 Fixed numeric scale (designer-provided)

0, 4, 5, 6, 7 px (micro gaps), 35, 53 px (special layout), and negative offsets -12, -2, -1 px.

The export also contains many decimal auto-layout "gap" values (e.g. 130, 238, 981.25, 1520.55) captured directly from Figma frames — not a spacing scale; do not reuse. TBD by designer for scale rationalization.

3.3 Layout conventions (from previous proposal, mapped to new scale)

4. Radius

5. Elevation & shadow

No elevation/shadow tokens exist in the export. The dp scale below is a proposal built from Black + the export's opacity tokens (shadow color #000000 at 10% per step). TBD by designer — every row is a starting point.

Supporting export tokens: opacity.10/50/60/70/80/90/100 (scrim/overlay steps), stroke weight.1 (1px) / .2 (2px) for borders, shadow = Black.

6. Motion

No motion tokens in the export — still proposed (previous status).

Reduce-motion (platform setting): m-instant for all, no parallax, no stagger.

7. Iconography

No icon tokens in the export — Material Symbols remains the proposal (previous status). Confirm pack with designer before build.

Material Symbols (outlined, weight 400, optical 24). Sizes: 16/20/24/32/40. Status icons use filled variant. All icons need a text label or tooltip+Semantics.label.

8. Breakpoints (responsive)

9. Touch targets

Minimum 48 × 48 dp tappable; list rows ≥ 56 dp; FAB 56 dp; 44 dp acceptable for dense inline controls (chip remove, icon buttons with tooltips).

10. Light/dark parity rules

• No color hardcoded in widget code — always token references
• Surface contrast ≥ 3:1 for UI chrome, ≥ 4.5:1 for text
• Elevation substitutes for color on dark surfaces
• Both modes must pass the QA color checklist (see 10_QA_Baseline.md)
• Dark chromatic roles are TBD by designer (§1.4) — gate dark-mode ship on sign-off

03 — Component Library (Shared)

• A. Feedback & states
  • AppSkeleton
  • AppEmptyState
  • AppErrorState
  • AppOfflineBanner
  • AppSnackbar / AppToast
  • AppBanner
• B. Inputs
  • AppTextField
  • AppDropdown (single select)
  • AppSearchBar
  • AppChips (filter/tag/input)
  • AppDatePicker / AppTimePicker
  • AppSwitch / AppCheckbox / AppRadio
  • AppSlider
• C. Display
  • AppCard
  • AppListTile
  • AppAvatar
  • AppBadge
  • AppProgress
  • AppTabs
  • AppCharts
  • AppAvatarStack, AppStatTile, AppInfoRow
• D. Navigation & actions
  • AppFAB
  • AppButton (M3)
  • AppDialog
  • AppBottomSheet
  • AppMenu (context menu)
  • AppTabBarTop + AppNavigationBar + AppNavigationDrawer + AppNavigationRail
• E. Content & media
  • AppSectionHeader
  • AppAttachmentTile
  • AppMarkdownViewer
  • AppStepper
  • AppQRScanner
• F. Shared interaction patterns
• G. Golden-test coverage expectation

Every reusable client component shared across modules. Module docs 07_Component_Library.md list module-specific components and reference these by name. Flutter mapping assumes Material 3 (flutter/material, Material3 ThemeData).

A. Feedback & states

AppSkeleton

• Purpose: loading placeholder for lists/cards/text.
• Props: variant (text|circle|rect|list|card), width, height, lines, radius.
• States: shimmer loop (m-slow), reduced-motion = static tint.
• Tokens: surfaceVariant fill, e-0. Flutter: custom Skeleton widget or shimmer package wrapper (prefer custom to avoid dep).

AppEmptyState

• Purpose: empty/zero-result content.
• Props: icon, title, message, actionLabel, onAction, compact.
• States: default; compact (inline list header).
• A11y: container Semantics(label: title + message).
• Tokens: displaySmall title, bodyMedium onSurfaceVariant. Flutter: Column + Icon + Text + FilledButton.tonal.

AppErrorState

• Purpose: full-screen or inline fetch failure.
• Props: code (error code from envelope), message, onRetry, details?, compact.
• Rules: never expose stack/server internals; 500 → generic text + requestId hint.
• Tokens: error icon, titleLarge, bodyMedium. Flutter: ErrorWidget-free custom widget.

AppOfflineBanner

• Purpose: top banner when connectivity lost.
• Props: visible, text (i18n offline.banner), onRetry.
• Behaviour: auto-dismiss on connectivity restore; sticky at top, e-1.
• Tokens: tertiaryContainer background. Flutter: MaterialBanner or custom AnimatedContainer.

AppSnackbar / AppToast

• Purpose: transient feedback (success, error, info, undo).
• Props: type, message, actionLabel?, onAction?, duration.
• Rules: one snackbar at a time (queue), error type persists ≥ 4 s, success < 3 s.
• Tokens: inverse surface, error/success icon accents. Flutter: ScaffoldMessenger wrapper.

AppBanner

• Purpose: persistent inline message (e.g., "results published", "pending KYC docs").
• Props: severity (info|success|warning|error), title, body?, dismissible.
• Tokens: *Container role colors. Flutter: MaterialBanner.

B. Inputs

AppTextField

• Props: label, hint, placeholder, keyboardType, textInputAction, formatters, validator, maxLength, prefix/suffixIcon, obscure, autofillHints, errorText, helperText, enabled, autofocus.
• States: empty, filled, focused, error, disabled, read-only, loading (suffix spinner).
• Validation: validator run on submit + on change after first error; error clears on edit.
• A11y: label + Semantics(error) on error; error announced.
• Tokens: surfaceVariant fill, outline border, error on error, focus primary.
• Flutter: TextField/TextFormField with InputDecoration, InputFormatters.

AppDropdown (single select)

• Props: label, items[{value,label}], value, onChanged, searchable?, loading?, emptyText, errorText, disabled.
• Behaviour: opens AppBottomSheet picker or menu; selected value shown in field.
• A11y: role "combobox", Semantics on options.
• Flutter: custom field + showModalBottomSheet, or DropdownButtonFormField for ≤ 8 items.

AppSearchBar

• Props: hint, debounceMs (default 300), onQuery, autofocus, suffix (clear), trailing (filter chips button).
• Behaviour: debounced server search; clear restores list; stays on screen during search.
• A11y: label, results announced (liveRegion).
• Flutter: SearchBar (M3) with controller + debounce Timer.

AppChips (filter/tag/input)

• Props: label, selected, onToggle, avatar?, onDelete? (input chips).
• Flutter: FilterChip/InputChip/ActionChip.

AppDatePicker / AppTimePicker

• Props: label, value, min/maxDate, onChanged, errorText.
• Behaviour: opens M3 date/time picker dialog; locale-aware formatting; m-base transition.
• Flutter: showDatePicker/showTimePicker wrappers; MaterialLocalizations.

AppSwitch / AppCheckbox / AppRadio

• Standard M3 controls; props: label, value, onChanged, disabled, subtitle?.
• A11y: label semantics, Semantics(toggled:)/checked:.
• Flutter: Switch, Checkbox, Radio with ListTile wrappers.

AppSlider

• Props: label, min/max/divisions, value, onChanged, valueLabel.
• Flutter: Slider + SliderTheme.

C. Display

AppCard

• Props: title?, subtitle?, trailing?, leading?, onTap?, elevation (e-0/e-1), padding, child.
• Variants: flat (e-0), outlined (outlineVariant), tonal (primaryContainer).
• A11y: whole-card tap = one Semantics(button:); inner controls excluded from card tap.
• Flutter: Card/Card.filled with InkWell.

AppListTile

• Props: leading, title, subtitle, trailing, onTap, dense?, selected?, badge?, menu? (trailing overflow menu).
• Height ≥ 56; dense ≥ 48. Flutter: ListTile with custom MenuAnchor.

AppAvatar

• Props: name, photoUrl?, size (24/32/40/48/64), presence?, onTap.
• Fallback: initials from name on primaryContainer. Flutter: CircleAvatar + CachedNetworkImage-style cache.

AppBadge

• Props: text, color (role), icon?, outlined?. Flutter: Badge/custom Container.

AppProgress

• LinearProgressIndicator (paged loads) / CircularProgressIndicator (buttons, refresh).
• Tokens: primary. Reduced-motion: determinate only.

AppTabs

• Props: tabs[{label, icon?, badge?}], controller, scrollable?, onChanged.
• Flutter: TabBar + TabBarView (keep-alive lists).

AppCharts

• Purpose: KPI visualization (dashboard, reports, fees).
• Props: type (bar|line|donut|gauge), series, labels, emptyText, height.
• Rules: show values in tooltips + data labels; a11y: provide Semantics summary text; provide tabular fallback when charts not meaningful.
• Flutter: fl_chart (recommended, already industry standard; verify license) — wrap in own AppChart widget so the lib is swappable.

AppAvatarStack, AppStatTile, AppInfoRow

• StatTile: label, value, delta?, trend? for dashboards.
• InfoRow: label, value, icon? for detail screens.

D. Navigation & actions

AppFAB

• Props: icon, label? (extended), onPressed, heroTag (unique per screen!).
• Rules: one FAB per screen; hidden on scroll-down, shown on scroll-up (list screens).
• Flutter: FloatingActionButton/FloatingActionButton.extended; scroll listener.

AppButton (M3)

• Variants: filled (primary CTA), filledTonal (secondary), outlined (tertiary), text (inline), icon (icon button w/ tooltip).
• Props: label, icon?, loading? (spinner replaces icon), enabled, destructive? (error colors), fullWidth?, semanticLabel.
• Height 40/48; touch target ≥ 48.
• Flutter: FilledButton, FilledButton.tonal, OutlinedButton, TextButton, IconButton with Tooltip.

AppDialog

• Props: title, content, actions, dismissible (barrier), destructiveAction?.
• Behaviour: barrier tap = cancel unless dismissible=false; ESC/back closes; focus moves into dialog; m-base scale+fade.
• Flutter: showDialog + AlertDialog; FocusScope.

AppBottomSheet

• Props: title, draggable (drag handle), showDragHandle, children, isDismissible, height (half/full).
• Rules: used for pickers, actions, filters; returns value via Navigator.pop(result).
• Flutter: showModalBottomSheet with DragHandle (M3).

AppMenu (context menu)

• Props: items[{label, icon?, destructive?, onTap}], semanticLabel.
• Behaviour: long-press / trailing overflow opens MenuAnchor; ESC closes; focus ring.
• Flutter: MenuAnchor + MenuItemButton.

AppTabBarTop + AppNavigationBar + AppNavigationDrawer + AppNavigationRail

• AppNavigationBar: bottom nav for phones (3–5 destinations, AppDestinations list).
• AppNavigationDrawer: full menu (all sections) for large screens; slide-in on phone via hamburger.
• AppNavigationRail: tablet/desktop ≥ 840 dp.
• Rules: selected destination = primary indicator (pill); badges show unread counts.
• Flutter: NavigationBar, NavigationDrawer, NavigationRail.

E. Content & media

AppSectionHeader

• Props: title, actionLabel?, onAction?, subtitle?. Section gaps 24 top.
• Flutter: Row with titleMedium + TextButton.

AppAttachmentTile

• Props: name, size, type, url, onPreview, onDownload?, uploading?, onRemove?.
• Preview: PDF/image viewers; files open in external viewer via share sheet.
• Flutter: ListTile + file-type icon map.

AppMarkdownViewer

• Purpose: homework descriptions, announcements, notices.
• Props: data, compact?, onLinkTap.
• Flutter: flutter_markdown (wrap; sanitize links).

AppStepper

• Purpose: multi-step flows (enrollment, admission, bulk import wizard).
• Props: steps[{title, state}], currentIndex, onStepTap?.
• Flutter: custom horizontal stepper; vertical on desktop.

AppQRScanner

• Purpose: biometric check-in, transport pickup, library issue (forward-looking: requires backend QR code support — see assumptions).
• Props: onScanned, pauseAfterScan, flashToggle?.
• Flutter: mobile_scanner package (wrap).

F. Shared interaction patterns

• Pull-to-refresh on all scrollable lists → RefreshIndicator; triggers reload + WS resubscribe.
• Infinite scroll for paginated lists → bottom CircularProgressIndicator + m-instant fade; "end of list" footer with bodySmall text.
• Optimistic updates on mark-read, toggles, likes; rollback on error + snackbar.
• Undo pattern: destructive-ish non-soft actions (delete homework draft, remove attachment) → snackbar with UNDO within 4 s.
• Empty→loading→error state machine per screen, never blank.

G. Golden-test coverage expectation

Every shared component has a golden test at 3 sizes (phone/tablet/desktop) + dark mode.

04 — Design System Mapping (Shared)

• 1. Theme
• 2. Widget → token mapping (core)
• 3. Typography mapping
• 4. Iconography
• 5. Motion mapping
• 6. Layout tokens
• 7. Theming rules (enforced)
• 8. Web/desktop (Flutter Web + Windows/macOS/Linux)

Maps Material 3 + Flutter widgets to the StudyLyon token set. Module docs 11_Design_System_Mapping.md extend this with module-specific components.

1. Theme

2. Widget → token mapping (core)

3. Typography mapping

4. Iconography

• Pack: Material Symbols outlined; 24 dp default; status icons filled.
• Sizing: 16 (dense rows), 20 (menu), 24 (default), 32 (empty state), 40 (headers).
• Color: onSurfaceVariant default; primary active; error destructive.

5. Motion mapping

6. Layout tokens

7. Theming rules (enforced)

1. No literal Color in widget code — context.colorScheme.* / AppTokens.* only.
2. No literal padding/margin — AppSpacing.* only.
3. No literal durations — AppMotion.* only.
4. Dark mode is a first-class theme, not an overlay.
5. Tenant branding overrides primary at runtime via ThemeData copy.

8. Web/desktop (Flutter Web + Windows/macOS/Linux)

• Hover states on all tappables (MouseRegion), focus rings (FocusTraversalGroup), keyboard shortcuts (Shortcuts/Actions), ESC closes dialogs/sheets/menus.
• Responsive layout via LayoutBuilder breakpoints (02_Design_Tokens.md §8).
• Scrollbars always visible on desktop.

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.

06 — State Management (Shared Architecture)

• 1. Stack
• 2. Layering
• 3. Base patterns (shared)
  • 3.1 Async state machine
  • 3.2 Pagination cubit (mixin)
  • 3.3 Cache & staleness
  • 3.4 Realtime
  • 3.5 Optimistic updates
  • 3.6 Auth state
  • 3.7 Connectivity state
• 4. Event/state conventions
• 5. Error handling (client)
• 6. Testing hooks

Recommended client state architecture (Bloc/Cubit). Decision status: proposal — flagged because no client exists yet. Module docs 13_State_Management.md define per-screen states on top of these conventions.

1. Stack

• flutter_bloc (Bloc + Cubit). Why: strict state transitions, testability, team familiarity.
• No additional state libs; DI via get_it or provider — recommend get_it + injectable.
• Server state: repository layer with dio; cache via Hive/shared_preferences for small config and drift only if offline queues grow (YAGNI: start with in-memory + shared_preferences).

2. Layering

UI (widgets) → Cubit/Bloc → Repository → DataSource (dio/WS) → API
                                └─ Cache (memory / prefs)

• Widgets never call repositories directly; they emit events / read state.
• Repositories are the only layer touching HTTP; they map envelopes to models and throw typed exceptions (ApiException(code, status, message)).

3. Base patterns (shared)

3.1 Async state machine

sealed class LoadState { Initial, Loading, Success, Error(ApiException) }

Every list/detail cubit exposes LoadState + data. UI maps:

• Initial/Loading → AppSkeleton
• Error → AppErrorState(code, message, onRetry)
• Success + empty → AppEmptyState
• Success + data → content

3.2 Pagination cubit (mixin)

mixin PaginatedListMixin<T> {
  int page; bool hasNext; bool isLoadingMore; List<T> items;
  // loadFirst() -> emits Loading; loadMore() -> appends; pullToRefresh() -> resets
}

Contract mirrors API: page, limit (default 20, max 100), sort (-field), q. meta from envelope: totalItems, totalPages, hasNext, hasPrevious.

3.3 Cache & staleness

• Repository caches last successful list per key (sl:cache:{module}:{query} client-side).
• Stale-while-revalidate: show cache instantly, refresh in background, update on success.
• TTLs: reference data (classes, subjects) 24 h; volatile lists (attendance today) 5 min; detail views no client cache (server caches).
• RefreshIndicator always bypasses cache.

3.4 Realtime

• WS gateway (/ws via WsModule) delivers notification.new, message.new, announcement.published, attendance.changed, invoice.updated events to user rooms.
• Cubits subscribe via repository subscribe(channel) → pushes events into state.
• On reconnect: resubscribe + pull-to-refresh equivalent (re-fetch current screen).
• App in background: WS paused; notifications surface via push; on resume → re-fetch.

3.5 Optimistic updates

• Mutations that are safe (toggles, mark-read, status changes) apply locally first, then call API; on error: rollback + AppSnackbar(error); on success: reconcile with server payload.
• Mutations with side effects (payments, publishing results) are never optimistic.

3.6 Auth state

• AuthCubit: unauthenticated → authenticating → authenticated(user, tenant) → refreshing → sessionExpired.
• Token refresh on 401 (dio interceptor, single-flight); on refresh failure → sessionExpired → login screen with reason snackbar.
• Permission changes trigger route rebuild.

3.7 Connectivity state

• ConnectivityCubit (internet_connection_checker or connectivity_plus): online/offline.
• Offline: banner (AppOfflineBanner), reads from cache, writes queued (only where module docs define offline write queues — attendance bulk, homework drafts), auto-flush on reconnect with idempotency keys.

4. Event/state conventions

• Load{Entity}, Refresh{Entity}, LoadMore, Retry, ChangeFilter, Submit, Clear naming.
• One Cubit per screen; shared selectors for cross-screen data (current user, current academic year, feature flags).
• FeatureFlagsCubit gates UI per tenant (biometric, SMS, WhatsApp channels).

5. Error handling (client)

6. Testing hooks

• Cubits are pure-Dart, unit-testable with mocked repositories.
• AppStateObserver logs transitions (dev only).
• Every cubit has a widget-test pair driving AppSkeleton/AppErrorState/AppEmptyState permutations.

07 — API Conventions (Shared)

• 1. Base
• 2. Success envelope (exact)
• 3. Error envelope (exact)
• 4. Rate limits (client-relevant)
• 5. Pagination & filtering conventions
• 6. Multi-tenancy & auth
• 7. Caching (client + server)
• 8. Realtime (WebSocket)
• 9. Optimistic UI & idempotency (client contract)
• 10. Offline strategy
• 11. Security (client obligations)
• 12. Versioning

Exact wire contract of the StudyLyon API, derived from source (ResponseEnvelopeInterceptor, HttpExceptionFilter, PaginationQueryDto, rate-limit guards, WsModule). Module docs 12_API_Mapping.md map screens to endpoints using only these shapes.

1. Base

• Base URL: https://api.<domain>/api/v1 (version prefix v1; see version.constants.ts).
• Content-Type: application/json; multipart for file uploads.
• Auth: Authorization: Bearer <accessToken>; refresh via POST /auth/refresh.
• Request ID: server echoes x-request-id; client sends its own UUID when absent.
• API keys (X-API-Key) for M2M — not used by the client app.

2. Success envelope (exact)

{
  "success": true,
  "message": "OK",
  "data": { },
  "meta": { },
  "timestamp": "2026-08-02T10:00:00.000Z",
  "requestId": "..."
}

• Paginated endpoints return data = array, meta = { page, limit, totalItems, totalPages, hasNext, hasPrevious }.
• Non-paginated endpoints omit meta.

3. Error envelope (exact)

{
  "success": false,
  "message": "Validation failed.",
  "error": { "code": "VALIDATION_ERROR", "details": [{ "field": "email", "message": "..." }] },
  "timestamp": "...",
  "requestId": "..."
}

4. Rate limits (client-relevant)

5. Pagination & filtering conventions

• Query: page (1-based), limit (1–100, default 20), sort (field or -field), q (global search term where the controller supports it).
• Filters are controller-specific query params (documented per module).

6. Multi-tenancy & auth

• Every request carries JWT with tenantId claim; server derives tenant from token — client never sends tenantId in the body.
• Guard: Public() decorator exempts auth endpoints only.
• Cross-tenant access → 403/404; client treats as permission/not-found.

7. Caching (client + server)

• Server: Redis cache sl:{tenantId}:{key}, TTL per module; dashboard KPIs cached.
• Client: last-good cache + stale-while-revalidate (06_State_Management.md §3.3).
• No Cache-Control guarantees from API — client caching is advisory.

8. Realtime (WebSocket)

• Gateway: WS upgrade with Authorization: Bearer <token> (or first-message auth).
• Channels: per-user room user:{userId}; topics notification.new, message.new, announcement.published, attendance.changed, invoice.updated, results.published.
• Message shape: { type: topic, tenantId, data, timestamp }.
• Disconnect → buffered in-app notifications delivered via REST on next fetch.

9. Optimistic UI & idempotency (client contract)

• Safe mutations: PATCH read, status toggles → optimistic + rollback.
• Write-once ops (payment, publish, submit) → show server result, no local write.
• Client sends Idempotency-Key header (UUID) on critical POSTs where the module API supports dedup; retry-safe by design otherwise.

10. Offline strategy

• Reads: last-good cache, offline banner, Retry on every failure.
• Writes: only module-defined queues (attendance bulk, homework draft) with local persistence + flush on reconnect + idempotency keys.
• Files: uploads resume-capable (chunked) only where backend supports it — otherwise queue with retry + DLQ visibility.

11. Security (client obligations)

• Tokens in secure storage (Keychain/Keystore), never logs.
• Biometric gate for sensitive screens (payments, admin settings) — forward-looking (backend 2FA exists; client-side gate is app-level).
• TLS only; pinning per org policy.
• All error UI derived from server codes — never render raw server messages that may contain internals (use i18n keys, fall back to message for 4xx business text only).

12. Versioning

• v1 current; breaking changes → new version prefix; client negotiates via Accept: application/vnd.studylyon.v1+json if backend adds it (flag: not in code yet).

08 — Interaction & Motion (Shared)

• 1. Touch gestures (phone/tablet)
• 2. Desktop/web (mouse + keyboard)
• 3. Haptics (mobile)
• 4. Motion language
• 5. Micro-interaction catalogue
• 6. Frustration controls

Global interaction conventions and motion language. Module docs 10_Interaction_Specification.md specialize per module.

1. Touch gestures (phone/tablet)

2. Desktop/web (mouse + keyboard)

3. Haptics (mobile)

4. Motion language

• Enter: new screen slides forward (m-base); content fades + slight rise (m-slow).
• Exit: reverse slide; dialogs/sheets scale+fade in, slide down on dismiss.
• Hero: shared-element flight for list→detail (avatar→profile header, thumbnail→ attachment preview) m-slow.
• State change: color/size transitions m-fast; icon morph via AnimatedSwitcher.
• Skeleton→content: cross-fade m-slow, no pop.
• Reduced motion (accessibility setting): all transitions become fades ≤ m-instant; no parallax, no stagger, no shimmer loop.
• Density: never animate layout shifts; use AnimatedSize for expanding sections.

5. Micro-interaction catalogue

6. Frustration controls

• Every interactive element responds within 100 ms of press (press state visible).
• Network-bound actions always show pending state — never a silent wait.
• Repeated taps on submit are disabled while pending (anti-double-submit).
• m-fast ripple only — no full-screen flashes.

09 — Accessibility Baseline (Shared)

• 1. Standards
• 2. Contrast (light & dark)
• 3. Touch & pointer targets
• 4. Dynamic type / text scaling
• 5. Semantics (TalkBack / VoiceOver)
• 6. Focus (keyboard, desktop, TV)
• 7. Screen reader labels (canonical patterns)
• 8. Motion & vestibular safety
• 9. Color-blind safe
• 10. Forms
• 11. Headings & landmarks
• 12. Testing checklist (per screen)

The mandatory accessibility standard every screen must meet. Module docs reference this; QA verifies per 14_QA_Checklist.md and this file's tables.

1. Standards

• WCAG 2.1 AA (perceivable, operable, understandable, robust).
• Material 3 accessibility guidance.
• Android TalkBack + iOS VoiceOver certified flows; Windows NVDA (web/desktop).

2. Contrast (light & dark)

3. Touch & pointer targets

• ≥ 48 × 48 dp tappable; 44 dp allowed for inline dense controls.
• ≥ 8 dp gap between adjacent targets.
• Desktop hover targets ≥ 32 px.

4. Dynamic type / text scaling

• All layouts must reflow up to 200% text scale without clipping (test at system font scales: default, 1.5×, 2×).
• maxLines/ellipsis only for labels, never for actionable content.
• No fixed-height containers for body text.

5. Semantics (TalkBack / VoiceOver)

• Every interactive element: label, role, state (checked/toggled/expanded), hint when needed.
• Decorative icons: excludeFromSemantics; icon-with-text buttons: single combined label.
• Screen readers announce: validation errors on focus, loading states, list position ("item 3 of 12"), empty-state messages.
• Live regions for: search results count, snackbar actions (UNDO), realtime updates (notification count), infinite-scroll load.
• Order: follows visual reading order (focus traversal verified per screen).

6. Focus (keyboard, desktop, TV)

• Visible focus ring (primary, 2 dp, offset 2) on all interactive elements.
• Logical FocusTraversalGroup per screen; modal dialogs trap focus.
• ESC exits modals; focus returns to trigger.

7. Screen reader labels (canonical patterns)

8. Motion & vestibular safety

• Reduced motion respected everywhere (see 08_Interaction_&_Motion.md §4).
• No flashing content > 3 flashes/sec.
• Autoplay only with user intent; no parallax.

9. Color-blind safe

• Never color-only status (attendance present/absent, fee paid/overdue): pair with icon
  • label (✓ present, ⚠ overdue).
• Approved combos: primary/onPrimary, error/onError, success/onSuccess with icons.

10. Forms

• Labels visible (not placeholder-only), associated with inputs.
• Errors: text + icon, announced, focus moved to first invalid field on submit.
• Autocomplete/autofill hints on auth, profile, address fields.

11. Headings & landmarks

• One headlineMedium per screen; logical h-hierarchy; sections use Semantics(headers:); desktop landmark navigation (skip links on web).

12. Testing checklist (per screen)

• TalkBack walkthrough: full flow without sight
• VoiceOver walkthrough: full flow without sight
• Keyboard-only desktop flow
• Text scale 2×: no clipping/overlap
• Contrast audit (light + dark)
• Focus order + visible focus ring
• Live regions announce async updates
• No color-only statuses

10 — QA Baseline (Shared)

• 1. Performance budgets
• 2. Offline matrix
• 3. Security checklist
• 4. Device matrix (P0)
• 5. Localization
• 6. Dark/light mode
• 7. Animation QA
• 8. Analytics events (shared)
• 9. Test pyramid (client)
• 10. Release gates

Cross-module quality gates every screen/module must pass. Module 14_QA_Checklist.md files add module-specific items to this baseline.

1. Performance budgets

2. Offline matrix

3. Security checklist

• No tokens/logs in crash reports, analytics, or screenshots
• Secure storage used for tokens (Keychain/Keystore)
• No secret in client binary (keys, URLs with secrets)
• Biometric/screen-lock gate on sensitive screens where defined
• All requests HTTPS; TLS 1.2+
• Server 5xx internals never surfaced in UI
• Idempotency headers on critical POSTs
• Session expiry → graceful re-login, state preserved where safe

4. Device matrix (P0)

5. Localization

• i18n via flutter_localizations; backend i18n module exists (i18n controller) — client strings client-side; server strings rendered through i18n keys where provided.
• RTL readiness: layout direction follows locale; no hardcoded alignment.
• Date/time/number formatting via Intl locale.
• Text scale & string length: German/French/Hindi/Spanish smoke strings must not break layouts (flag: actual supported locales = org config; base English + platform).

6. Dark/light mode

• Full visual QA pass in both modes on every screen.
• No hardcoded colors; tokens only (enforced by code review + golden tests).

7. Animation QA

• All transitions m-* tokens; reduced-motion respected.
• No dropped frames during hero/transitions (profile 120 fps).
• Haptics only where defined; none on desktop.

8. Analytics events (shared)

All module events follow: {module}.{screen}.{action} (e.g., students.list.search). Common events: app.launch, auth.login.success|failure, screen.view, search.perform, offline.enter|exit, error.viewed(code), sync.flush. Proposal flag: analytics SDK not selected; events are contract for later wiring.

9. Test pyramid (client)

10. Release gates

• Typecheck + lint + full test suite green
• Perf budgets met (profiled)
• A11y checklist per changed screen
• Offline matrix pass
• Cross-tenant & permission scenarios (403/404) pass
• No console errors / crash-free session rate ≥ 99.9%

11 — Flutter App Architecture (Shared)

• 1. Project & dependencies
• 2. DI (get_it)
• 3. Module folder structure (per module)
• 4. DTO → model mapping
• 5. Networking
• 6. Router (go_router)
• 7. Theme
• 8. Extensions (shared)
• 9. Localization
• 10. Analytics
• 11. Storage & security
• 12. Testing strategy
• 13. Performance
• 14. CI/CD (proposal)

How the Flutter client is built. Module docs 15_Flutter_Implementation_Guide.md extend this with module-specific structure. Forward-looking spec (no client repo exists yet).

1. Project & dependencies

studylyon_app/          (Flutter 3.x, Dart 3)
├── lib/
│   ├── main.dart
│   ├── app.dart
│   ├── core/            # di, router, theme, dio, storage, i18n, analytics, ws
│   ├── features/
│   │   └── <module>/    # data, domain, presentation (see §3)
│   └── shared/          # shared widgets, mixins, extensions
└── test/                # unit, widget, golden, integration

Recommended deps (verify licenses): flutter_bloc, dio, go_router, get_it, hive (cache) or shared_preferences, intl, flutter_localizations, connectivity_plus (or internet_connection_checker), fl_chart, mobile_scanner (flagged), flutter_markdown, cached_network_image, secure_storage, uuid.

2. DI (get_it)

• AppDio (authenticated client), AuthRepository, TenantRepository, module repositories, cubits (lazy factory). No singletons holding per-screen state.

3. Module folder structure (per module)

features/<module>/
├── data/
│   ├── dto/<entity>_dto.dart        # envelope-payload mappers
│   ├── models/<entity>.dart         # domain models
│   └── repositories/<entity>_repository.dart
├── domain/
│   └── (optional) use cases when > 1 repo interaction
└── presentation/
    ├── cubit/<screen>_cubit.dart
    ├── pages/<screen>_page.dart
    └── widgets/<screen-specific widgets>

4. DTO → model mapping

• API payload → *Dto.fromJson (validate types) → domain model (normalized ids, enums, dates DateTime, money in minor units int).
• Serialization with json_serializable (build_runner) or hand-written fromJson (small modules) — pick one, prefer codegen for consistency.
• Never pass DTOs into widgets; widgets consume models.

5. Networking

• AppDio: base URL, bearer interceptor (auto-attach token), refresh interceptor (single-flight refresh, queue requests), error interceptor mapping envelope → typed ApiException (code/status/fieldDetails), idempotency header helper, requestId header, timeout 15 s (uploads 120 s).
• WS: WsClient (socket.io-client or dart web_socket_channel per backend gateway — verify backend protocol; flagged assumption) with auto-reconnect + backoff.

6. Router (go_router)

• AppRouter: GoRouter with StatefulShellRoute.indexedStack branches per top-level destination; route guards: authGuard, permissionGuard('x.y'), tenantGuard.
• Deep links: Uri route table in module docs; push-notification tap → navigate by path.
• 403/404/500 error screens registered globally.

7. Theme

• AppTheme.light()/dark() from 02_Design_Tokens.md; org branding override; MaterialApp(theme, darkTheme, themeMode, locale, localizationsDelegates).

8. Extensions (shared)

• context helpers: spacing, colorScheme shortcuts, showAppSnackbar(type, message, action).
• String: toDate, capitalize, maskedEmail, initials.
• int: toMoney(currency), toOrdinal.
• DateTime: toDisplayDate(locale), startOfDay, isSameDay, weekdayLabel.
• List: groupBy, chunk.

9. Localization

• .arb files: app_en.arb, app_fr.arb, … (start: en; add per org demand).
• AppLocalizations generated (intl_utils); all user-facing strings via keys — including server messages mapping (error code → key, fallback to server message only for business 4xx text).

10. Analytics

• AnalyticsService interface (firebase_analytics recommended; swappable); events per 10_QA_Baseline.md §8; consent-gated; no PII beyond necessity.

11. Storage & security

• flutter_secure_storage: access/refresh tokens, session meta.
• shared_preferences: theme, locale, onboarding flags, cache of reference data.
• Hive (if adopted): paginated list caches per module key {tenant}:{module}:{query}.

12. Testing strategy

• Unit: cubits (mock repos), validators, formatters, mappers.
• Widget: state-machine tests per screen; golden per shared component + screen (light/dark, 3 sizes); fonts bundled in test assets for stable goldens.
• Integration: integration_test journeys: login → home; attendance mark flow; invoice pay flow; offline banner behavior.
• E2E: device-cloud smoke per release (P0 journeys).
• Run: flutter analyze, flutter test, flutter test integration_test -d <device>.

13. Performance

• const constructors everywhere; ListView.builder mandatory for lists; RepaintBoundary on charts/media; image cache cached_network_image with resize; shader compilation jank → target Android 15+ Impeller; defer heavy init off first frame; isolate for CSV parsing (bulk import preview).
• Profile every release on mid-range device against 10_QA_Baseline.md §1.

14. CI/CD (proposal)

• GitHub Actions: analyze → unit → widget → golden → integration (Android emulator + Chrome) → build signed AAB/IPA; screenshots for QA on PRs (golden diffs).

12 — Assumptions & Open Questions (Shared)

• A. Product-level
• B. API / backend
• C. Product decisions deferred (no backend signal)
• D. Design system
• E. Governance

Every cross-cutting uncertainty affecting the whole design-docs set. Module docs list their own module-specific items; this file is the global ledger.

A. Product-level

B. API / backend

C. Product decisions deferred (no backend signal)

D. Design system

E. Governance

• When any of the above is resolved, the owning doc(s) must be updated; module docs should not contradict this ledger.
• Any doc that invents a feature absent from source violates policy — reviewers check derivability. Items above are the only sanctioned extrapolations.

01 — Product Overview (Academics Module)

• 1. Purpose
  • 1.1 Why it is the backbone
• 2. Business goals
• 3. User goals
• 4. Stakeholders
• 5. Why this exists
• 6. Dependencies
• 7. Success metrics
• 8. Edge cases
• 9. Assumptions (module)
• 10. Open questions (module-level; global ledger in 00-shared/12)
• 11. Glossary (this module)

StudyLyon — multi-tenant ERP / School Management API. This package designs the Academics module client (Flutter, forward-looking spec) against the implemented NestJS backend. All endpoints, DTO fields, schemas, indexes, business rules, and wire contracts are derived directly from src/modules/academics/**, src/database/base.*, src/common/dto/pagination-query.dto.ts, studylyon-blueprint/03-Database/*, 04-Modules/*, PLAN.md, and docs/IMPLEMENTATION_PLAN.md. No feature is invented; gaps are flagged in the Assumptions & Open Questions section.

1. Purpose

Academics is the structural backbone of StudyLyon. It defines the five reference entities every operational module hangs off:

1.1 Why it is the backbone

Downstream modules reference these entities by ObjectId and are meaningless without them (verified in source):

• Timetable requires classId, subjectId, teacherId, academicYearId (timetable/schemas/timetable.schema.ts:18-40).
• Attendance requires classId (attendance/schemas/attendance.schema.ts:28-29).
• Students enrollment binds to classId per year (blueprint 04-Modules/Students.md:31).
• Homework / Exams / Results / Fees consume classes and subjects as reference data (blueprint 04-Modules/Exams.md:51, 03-Database/RELATIONSHIPS.md §4, §6).

The canonical hierarchy (blueprint 03-Database/RELATIONSHIPS.md:50-61):

organizations
  └─ academic_years (many, per tenant)
        └─ grades (many)
              └─ sections (many)
                    └─ classes (many)   via gradeId + sectionId
                          ├─ students (many via class_enrollments)
                          ├─ timetables (many)
                          └─ homework (many)

subject_assignments binds the teaching staff into this tree (03-Database/RELATIONSHIPS.md:84-92):

teachers (1)
  └─ subject_assignments (many)   via teacherId
        ├─ subjects (via subjectId)
        └─ classes (via classId)

2. Business goals

3. User goals

• Organization admin: set up the year, grade ladder, sections, subjects once; flip the current year at rollover; see the whole structure at a glance.
• Academic coordinator: build grades → sections → classes, assign subjects and teachers per class per year, catch conflicts before timetabling starts.
• Teacher: see which classes/subjects they teach in the current year; use class lists to find their sections.
• Student / parent (read-only): browse the current year's structure — grade, section, class name, subject list — to understand where they sit.

4. Stakeholders

Platform operator, institution admins, academic coordinators, teachers, students, parents, timetable/attendance/homework/exam feature owners (consumers of this reference data), QA + design + engineering.

5. Why this exists

Every school runs on a fixed academic calendar and ladder. StudyLyon is multi-tenant with heterogeneous school structures (per blueprint COLLECTIONS.md:925-969); a tenant-defined year/grade/section/class tree is the precondition for enrollment, attendance, timetable, exams, and fees. Without this module those modules cannot target a student's actual teaching unit.

6. Dependencies

7. Success metrics

• Year setup (year → grade → section → class → subject → assignment) completed in < 15 min for a 12-grade school on a mid-range device.
• Zero duplicate master records per tenant (server 409s surfaced correctly, never silently overwritten).
• Hierarchy browse renders 12 grades × 4 sections × 40 classes with no jank (long-list budgets per 00-shared/10 §1).
• Conflict surface (duplicate class name, teacher double-booked) visible before timetable creation — flagged (planned) since the API has no conflict endpoint today (OQ-4).

8. Edge cases

• Duplicate academic-year name → 409 "Academic year "X" already exists." (academic-year.service.ts:27-28); duplicate grade name → 409 (grade.service.ts:23); duplicate subject code → 409 + unique index fallback (subject.service.ts:23-24, subject.schema.ts:38).
• Classes/sections/assignments have no duplicate guard in code — duplicate (gradeId, sectionId, name) classes and duplicate assignments are possible (OQ-4): class.service.ts:16-18, subject-assignment.service.ts:13-17.
• Soft delete everywhere (BaseRepository.softDelete, base.schema.ts:20-27) — lists hide deleted docs automatically; no cascade — deleting a grade leaves orphan sections/classes behind (OQ-3, RELATIONSHIPS.md:134-138).
• Grade/section/class status is a free string (schema default 'active'), not an enum — client must treat any non-'active' value as inactive (grade.schema.ts:21-22, section.schema.ts:24-25, class.schema.ts:33-34).
• set-current un-flags every isCurrent then flags the target and sets status: active (academic-year.service.ts:72-79); the target may have had status: upcoming or archived.
• Grade academicYearId is optional in both schema and DTO — grades can exist outside any year (grade.schema.ts:9-10, create-grade.dto.ts:5-8); class academicYearId is required (class.schema.ts:9-10).
• Subject marks are independent ints — no cross-field validation (theory+practical vs maximum, passing ≤ maximum) in DTO or service (create-subject.dto.ts:18-46, OQ-5).
• UpdateSubjectDto cannot change theoryMarks/practicalMarks (update-subject.dto.ts:4-42).
• Assignments have no GET /subject-assignments/:id and no update endpoint — remove + recreate is the only correction path (subject-assignment.controller.ts:19-39).
• class.campusId has ref: 'Class' in the schema (likely intended Campus) (class.schema.ts:12-13) and roomId is a free string, not a Room ref (class.schema.ts:30-31) — client renders these as opaque IDs/strings (OQ-6).
• Academic years list default sort createdAt: -1 (newest first) (academic-year.service.ts:47); grades default displayOrder: 1 (grade.service.ts:39); classes/sections/subjects/assignments are unsorted (insertion order) (class.service.ts:44-48, section.service.ts:41-48, subject.service.ts:35-47).

9. Assumptions (module)

• Mobile client is forward-looking: the backend is complete; this package is the UI-side spec against real endpoints.
• PRD / roadmap context: native mobile apps are out of Phase 1 scope (PRODUCT_REQUIREMENTS_DOCUMENT.md:144); roadmap Phase 3 = read-only companion — these docs still spec the full client per global decision A1 (00-shared/12 A1). Academics admin/coordinator editing is speced for tablet/desktop-first; phone gets read + quick actions.
• The coaching-extension plan (docs/IMPLEMENTATION_PLAN.md §6.2.1: sections → batches, subjectCategory, classType, batchId fields) is not in code; all of it is marked (planned) and never shown as implemented.
• The wire contract follows the fixed envelope; academics endpoints return raw Mongoose documents inside data (no field whitelisting/renaming at the API layer) — the client maps _id, __v, timestamps explicitly (base.schema.ts:7-35).
• No pagination helper exists on assignments/by-class/by-teacher lookups — they return bare arrays (subject-assignment.service.ts:19-31).

10. Open questions (module-level; global ledger in 00-shared/12)

11. Glossary (this module)

02 — User Personas (Academics Module)

• P1 — Organization Admin ("Nishant")
• P2 — Academic Coordinator ("Meera")
• P3 — Teacher ("Mr. Okafor")
• P4 — Student / Parent (read-only)
• Persona → capability matrix (intended; not enforced by API today)

Personas for the Academics module, derived from blueprint 01-Product/USER_PERSONAS.md role model (roles examples: Super Admin, Organization Admin, Teacher, Parent, Student — COLLECTIONS.md:600-623) and the endpoints/semantics in src/modules/academics/**. Permission notes reflect the actual guard state: every endpoint is JWT-authenticated but no academics.* permission exists yet (rbac/permissions.constants.ts:1-97, OQ-1 in 01_Product_Overview.md) — so the "can do X" columns below are the intended mapping, marked accordingly.

P1 — Organization Admin ("Nishant")

P2 — Academic Coordinator ("Meera")

P3 — Teacher ("Mr. Okafor")

P4 — Student / Parent (read-only)

Persona → capability matrix (intended; not enforced by API today)

Every write above currently requires only a valid JWT (academics.module.ts:46, controllers @UseGuards(JwtAuthGuard)). The matrix is the design target; enforcement is (planned) (OQ-1).

03 — User Journeys (Academics Module)

• 1. Create academic year + rollover
• 2. Create grade / section / class ladder
• 3. Assign subjects + teachers (assignment matrix)
• 4. Manage conflicts
• 5. Student-facing structure browse (read-only)
• 6. Cross-cutting exit / failure rules

End-to-end journeys computed from src/modules/academics/controllers/*, services/*, and the consumer modules (timetable, attendance). Mirror of the admin flow in docs/user-flows/END_TO_END_USER_FLOWS.md:111-138. Every step maps to an implemented endpoint; (planned) marks absent server features. Error codes per 00-shared/07 §3; conflict copy matches service strings exactly.

1. Create academic year + rollover

entry: Academics → Academic Years (admin); fresh tenant: empty state
intent: establish the session calendar and promote the current year

sequenceDiagram
    actor A as Org Admin
    participant Y as AcademicYearsScreen
    participant API as POST /academic-years
    A->>Y: "Add year" → form (name, startDate, endDate)
    Y->>API: {name:"2026-2027", startDate:"2026-04-01", endDate:"2027-03-31"}
    alt 200 created (status defaults upcoming)
        Y-->>A: new row, badge "Upcoming" (academic-year.service.ts:30-33)
    else 409 DUPLICATE_RESOURCE
        Y-->>A: inline "Academic year "2026-2027" already exists." (academic-year.service.ts:27-28)
    else 400 VALIDATION_ERROR
        Y-->>A: field errors (bad date string / missing name)
    end
    A->>Y: row → "Set as current"
    Y->>API: PATCH /academic-years/:id/set-current
    API-->>Y: 200 doc {isCurrent:true, status:"active"}
    Note over API: all other years unset isCurrent (academic-year.service.ts:72-77)
    Y-->>A: badge "Current" on target; former current loses badge

• Decision points: duplicate year (409) → jump to the existing row instead of forcing a rename; rollover is a destructive-ish global state flip — confirm dialog ("Old current year will stop being current") since it affects every downstream module's year filter.
• Failure covers: 401 (token expired → refresh → re-login), 429 RATE_LIMITED (countdown, no auto-retry), offline (blocked, cached list shown).
• Abandonment: back cancels form; no partial writes (create is atomic, service checks name first then repo.create).

2. Create grade / section / class ladder

entry: Academics → Grades / Classes (admin or coordinator)
intent: build the tenant's ladder, then the concrete classes

flowchart TD
    A[Open Grades] --> B{Grades exist?}
    B -- No --> C[POST /grades name=Grade 1, displayOrder=1]
    B -- Yes --> D[Next grade or skip]
    C --> E[repeat for Grade 2..12 with displayOrder++]
    D --> F{Create sections?}
    F -- Yes --> G[POST /sections gradeId, name=A/B/C]
    F -- No --> H[POST /classes academicYearId, gradeId, sectionId, name]
    G --> H
    H --> I[Class list shows grade+section chips]
    I --> J[Class detail: capacity, classTeacherId, roomId]

• Grade create: 409 if name taken (grade.service.ts:21-24) — client pre-checks the loaded list, but still renders server 409 inline (race-safe).
• Section create: no duplicate guard in code (section.service.ts:16-18) — client warns when (gradeId, name) repeats (OQ-4).
• Class create: requires academicYearId + gradeId + sectionId (all IsMongoId, create-class.dto.ts:5-20) — cascading pickers: year → grade → section (13_State_Management.md §2). Class name example "Grade 10 - A" (create-class.dto.ts:22); no uniqueness enforced (class.service.ts:16-18).
• Ordering: grades default sorted by displayOrder (grade.service.ts:39); classes/sections come back in insertion order (class.service.ts:44-48, section.service.ts:41-48) — client preserves server order, adds no re-sort.

3. Assign subjects + teachers (assignment matrix)

entry: Class detail → "Subjects & teachers" (coordinator)
intent: bind teacher×subject×class×year

sequenceDiagram
    actor C as Coordinator
    participant D as ClassDetail
    participant A as AssignmentsRepo
    participant API as POST /subject-assignments
    C->>D: open class (year-scoped)
    D->>API: GET /subject-assignments/by-class/:classId?academicYearId=
    API-->>D: existing roster []
    C->>D: "Add subject" → pick subject + teacher
    D->>API: {teacherId, subjectId, classId, academicYearId}
    alt 200
        D-->>C: row appears (SubjectAssignmentRow)
    else 400 VALIDATION_ERROR
        D-->>C: invalid ObjectId highlighted
    else 409/422 (planned: duplicate/conflict check)
        D-->>C: conflict banner — server does not check today (OQ-4)
    end
    C->>D: remove row → DELETE /subject-assignments/:id
    D-->>C: "Assignment not found." if stale (subject-assignment.service.ts:34)

• Duplicate assignments are possible server-side (no unique index, subject-assignment.schema.ts:22-25; no service check, subject-assignment.service.ts:13-17) — client disables an already-added (subject, teacher) pair in the picker to prevent double rows; treat as guard, not guarantee (OQ-4).
• No update endpoint — correcting teacher = delete + re-create (subject-assignment.controller.ts:19-39); UI offers "Replace" = delete + create.

4. Manage conflicts

entry: Class detail or Teacher roster, conflict detected by client

flowchart TD
    A[Client renders roster] --> B{Conflicts?}
    B -- Duplicate assignment (same subject twice) --> C[Warning banner + merge action]
    B -- Teacher double-booked across classes --> D[Warning: teacher teaches same subject in 2 classes]
    B -- Class without subjects --> E[Empty-state callout 'Add subjects']
    B -- Section/class orphaned (grade deleted) --> F[Orphan callout + 'reparent or archive']
    C --> G[Delete duplicate row]
    D --> H[Open teacher roster to review]
    E --> I[Jump to assignment matrix]
    F --> J[Delete orphan (soft) or move]

• All conflict signals are client-computed (server exposes raw lists only). (planned) server-side: validation on assignment create, cascade/orphan cleanup jobs (RELATIONSHIPS.md:134-138), per OQ-3/OQ-4.

5. Student-facing structure browse (read-only)

entry: Home → Academics (student/parent, read)
intent: see own grade/section/class + subjects for the current year

sequenceDiagram
    actor S as Student
    participant H as AcademicsBrowse
    participant R as ReferenceRepo
    participant API as GET /academic-years | /grades | /classes | /subjects
    S->>H: open Academics
    H->>API: current year (isCurrent=true resolved client-side from list)
    API-->>H: year {status:"active", isCurrent:true}
    H->>API: classes of year (GET /classes/by-year/:id)
    H-->>S: own class resolved via enrollment (client filter) — badge "Your class"
    H->>API: subjects (GET /subjects) + roster (by-class/:classId)
    H-->>S: tree: Grade 10 → Section A → Class "Grade 10 - A" → subjects w/ teachers

• Server has no "my data" scoping for structure (OQ-1 in 01); the client resolves the student's classId from enrollment (Students module) and filters client-side. Subject marks fields (max/passing) are not shown to students (client policy — server returns them in the same doc, subject.schema.ts:21-32).
• Offline: structure cached 24 h (13_State_Management.md §3) → read works offline.

6. Cross-cutting exit / failure rules

• Back = pop to list (state preserved via StatefulShellBranch, 00-shared/05 §3); abandonment at any form step = no server side-effects.
• Permission denial (when OQ-1 lands): 403 PERMISSION_DENIED → hidden CTAs + guarded routes (00-shared/05 §1).
• Session expiry mid-flow: silent refresh; failure → re-login, in-progress form preserved in memory.
• Offline: all writes blocked with AppOfflineBanner; cached reads allowed.

04 — Information Architecture (Academics Module)

• 1. Place in the global shell
• 2. Content model (exact, from schemas)
• 3. Navigation tree (forward-looking routes)
• 4. Sibling relationships (cross-module)
• 5. Information grouping rules

Where Academics lives in the app shell (00-shared/05) and how its screens nest. Routes are forward-looking (no client exists); the data model below is exact from src/modules/academics/** and 03-Database/RELATIONSHIPS.md:50-61.

1. Place in the global shell

Top-level destination (per 00-shared/05 §2):

Shell: phone bottom-nav + drawer; tablet/desktop NavigationRail; master-detail at ≥ 840 dp (00-shared/04 §6).

2. Content model (exact, from schemas)

Academic Year (academic_years)               name, startDate, endDate,
  status: upcoming|active|archived, isCurrent: bool
        └─ Grade (grades) [optional year binding]   name, code?, displayOrder, status
              └─ Section (sections)                 name, capacity=40, classTeacherId?, roomId?, status
                    └─ Class (classes)               academicYearId*, gradeId*, sectionId*,
                                                      name, capacity=40, campusId?, classTeacherId?,
                                                      roomId?, status
Subject (subjects) — flat catalog             code*, name, shortName?, credits=0,
                                               maximumMarks=100, passingMarks=33,
                                               theoryMarks=80, practicalMarks=20, status
Subject Assignment (subject_assignments)      teacherId*, subjectId*, classId*, academicYearId*

• Hierarchy is NOT denormalized: a Class references year+grade+section IDs; the client must join to render "Grade 10 · Section A" labels (class.schema.ts:9-19).
• Grades may float outside any year (grade.academicYearId optional — grade.schema.ts:9-10); classes may not (class.schema.ts:9-10).
• Subjects and assignments are year-agnostic catalogs except that assignments carry academicYearId (subject-assignment.schema.ts:18-19).

3. Navigation tree (forward-looking routes)

/academics                                Academics hub (admin/coordinator/read)
├── /academics/years                      Academic Year list
│   ├── /academics/years/new              Create year (full-screen form)
│   └── /academics/years/:id              Year detail (dates, status, classes of year)
│       └── /academics/years/:id/classes  Classes of this year (by-year feed)
├── /academics/grades                     Grades list (displayOrder ladder)
│   ├── /academics/grades/new             Create grade
│   └── /academics/grades/:id             Grade detail → sections of grade
│       └── /academics/grades/:id/sections  Sections list (by-grade feed)
├── /academics/classes                    Classes list (all)
│   ├── /academics/classes/:id            Class detail — MASTER screen
│   │   ├── tabs: Overview | Subjects & teachers | Students(link)
│   │   └── /academics/classes/:id/assign  Assignment matrix (add/replace/remove)
│   └── /academics/classes/new            Create class (cascading pickers)
├── /academics/sections                   Sections list (all)
│   └── /academics/sections/:id           Section detail (chips of classes)
├── /academics/subjects                   Subject catalog
│   ├── /academics/subjects/new           Create subject (marks form)
│   └── /academics/subjects/:id           Subject detail (marks config, usage)
├── /academics/explore                    Hierarchy explorer (tree view)
└── /academics/teachers/:teacherId        Teacher roster (by-teacher assignments)

Route guards: authGuard + permissionGuard('academics.read') — the permission string is (planned) (OQ-1); until the backend exposes it, the guard reads the tenant role set (00-shared/05 §9).

4. Sibling relationships (cross-module)

5. Information grouping rules

1. Year-first browsing: all admin reads default to the current year (isCurrent:true resolved from the years list, academic-year.service.ts:69-83); a global year switcher (AppBar chip) re-scopes every list that supports academicYearId.
2. Flat catalogs, joined display: subjects/grades/classes list pages render joined labels (grade name, section name) computed client-side from the loaded reference cache — never from a server-side projection.
3. Read vs admin surfaces: structure browse for students/parents reuses the same pages with all CTAs hidden (permission-driven), per 02_User_Personas.md P4.
4. Master-detail: class detail is the hub for the assignment matrix and downstream links (timetable/attendance/students); on tablet+ it opens in the right pane at ≥ 840 dp (00-shared/04 §6).

05 — Screen Inventory (Academics Module)

• 1. Academic Year List
• 2. Academic Year Detail
• 3. Grades List
• 4. Grade Detail (with sections)
• 5. Classes List
• 6. Class Detail — MASTER screen
• 7. Section Detail
• 8. Sections List
• 9. Subjects List
• 10. Subject Detail
• 11. Subject Assignment Matrix
• 12. Hierarchy Explorer
• 13. Teacher Roster (by-teacher)
• 14. Create/Edit forms (full-screen)
  • Screen → endpoint matrix

Every screen the Academics module needs, mapped to its exact endpoint source. All endpoints from src/modules/academics/controllers/*. Read/write split per 02_User_Personas.md matrix (intended, RBAC (planned) — OQ-1).

1. Academic Year List

2. Academic Year Detail

3. Grades List

4. Grade Detail (with sections)

5. Classes List

6. Class Detail — MASTER screen

7. Section Detail

8. Sections List

9. Subjects List

10. Subject Detail

11. Subject Assignment Matrix

12. Hierarchy Explorer

13. Teacher Roster (by-teacher)

14. Create/Edit forms (full-screen)

Routes /…/new and /…/:id/edit for year, grade, section, class, subject — one screen per entity, field specs in 08_Form_Specifications.md.

Screen → endpoint matrix

06 — Screen Specifications (Academics Module)

• 0. Shared chrome & conventions (all screens)
• 1. Academic Year List /academics/years
• 2. Academic Year Detail /academics/years/:id
• 3. Grades List /academics/grades
• 4. Grade Detail /academics/grades/:id
• 5. Classes List /academics/classes
• 6. Class Detail — MASTER /academics/classes/:id
• 7. Section Detail /academics/sections/:id
• 8. Sections List /academics/sections
• 9. Subjects List /academics/subjects
• 10. Subject Detail /academics/subjects/:id
• 11. Subject Assignment Matrix (full screen) /academics/classes/:id/assign
• 12. Hierarchy Explorer /academics/explore
• 13. Teacher Roster /academics/teachers/:teacherId
• Interaction & motion summary (module)
• Keyboard (desktop)

Production-grade specs for each Academics screen: chrome, states, components, micro-interactions, a11y, responsive, dark/light, keyboard, motion. Tokens: Sp = 00-shared/02 §3, Ty = typography §2, El = elevation §5, R = radius §4, Mo = motion §6. Components reference 00-shared/03 and module components in 07_Component_Library.md. Wire facts: all reads return raw docs in data; lists paginated with meta{page,limit,totalItems,totalPages,hasNext,hasPrevious} (pagination-query.dto.ts:32-39).

0. Shared chrome & conventions (all screens)

• Year switcher: AppDropdown chip in the AppBar (values = cached years, 13_State_Management.md §3); selection is a ReferenceScope in the cubit that re-scopes every academicYearId query; default = current year (isCurrent:true) or first year if none flagged.
• Permission gating: all CTAs hidden for read-only roles (P4, 02); route guard (planned) for academics.* perms (OQ-1). Until then, hide by role set.
• Status rendering: year status enum → badge (upcoming=outline, active=tonal/primary, archived=neutral) (academic-year.schema.ts:7-11); grade/section/class status is a free string — treat 'active' = on, anything else = archived badge (OQ-2 in 01).
• Empty states: one AppEmptyState per entity with its primary CTA.
• Loading: AppSkeleton(list) ≤ 200 ms to first frame; content ≤ 2 s (00-shared/10 §1).
• Errors: AppErrorState with server code; 409/422 → inline banner; 5xx → generic + requestId hint; 401 → silent refresh → re-login.

1. Academic Year List /academics/years

Chrome: AppBar "Academic Years" + year switcher (hidden on this screen); FAB "Add year" (extended, Icons.add); padding Sp.16 (phone) / Sp.24.

Row (AppListTile):

• Leading: year monogram avatar (Icons.calendar_month) — current variant primaryContainer.
• Title: name (Ty.titleMedium).
• Subtitle: startDate → endDate (locale Intl, dd MMM yyyy), bodySmall onSurfaceVariant.
• Trailing: status badge + AppMenu (Set as current / Edit / Delete).

States:

• idle → list from GET /academic-years (sort=-createdAt server default).
• paginated: hasNext → infinite scroll footer spinner (Mo.m-instant).
• pull-to-refresh: re-fetch page 1.
• current-year row pinned first with a primaryContainer leading pill "Current" (client sort: isCurrent desc, then server order).

Conflict-free actions: "Set as current" → AppDialog confirm ("This will un-flag all other years") → PATCH /academic-years/:id/set-current (academic-year.service.ts:69-83) → row badges re-render; snackbar "Year 2026-2027 is now current". Optimistic: no (server flips multiple docs) — server-first, success snackbar.

Delete: destructive AppDialog (typed confirm of the year name — irreversible-ish soft delete, 00-shared/05 §5); on 200 row removed with AnimatedList exit.

A11y: row Semantics(button) + "current/upcoming/active/archived"; badge announced; pagination live region "Loaded N of M years".

Tablet/desktop: master-detail at ≥ 840 dp — list left, detail right (/academics/years/:id); keyboard N = new year; Ctrl+Enter = set current.

2. Academic Year Detail /academics/years/:id

Chrome: AppBar back + title name; header card.

Header card (AppCard tonal when isCurrent):

• headlineMedium name; badge status + "Current" pill.
• Meta rows (AppListTile-like): Start date, End date (bodyMedium), Created (bodySmall).
• Actions row: TonalButton "Set as current" (hidden if already current); OutlinedButton "Edit" → form screen; icon menu → Delete.

Classes of this year section (titleMedium):

• Feed = GET /classes/by-year/:academicYearId paginated (class.controller.ts:30-35).
• Rows = class name + grade/section chips (client-joined), capacity.
• Tap → /academics/classes/:id (master screen).
• Empty → AppEmptyState compact "No classes yet for this year" + "Add class".

Edge: year status editable to archived even while isCurrent — client warns "Archiving the current year?" (server allows it — update-academic-year.dto.ts:20-27, academic-year.service.ts:59-67).

3. Grades List /academics/grades

Chrome: AppBar "Grades"; FAB "Add grade"; optional grade code chip.

Row:

• Leading: rank badge displayOrder (mono, Ty.labelMedium, circled).
• Title: name (Ty.titleMedium); trailing: code chip (mono) if set; status badge (non-active only); AppMenu (Edit / Delete).
• Subtitle: "N sections" (count from client cache of by-grade) + "N classes".

Ordering: server default displayOrder:1 (grade.service.ts:39) — no client re-sort; reorder = edit displayOrder (form field, Min(0)).

Create (screen 14.1): full-screen form (5+ fields) per 08 §1.

Conflict: server 409 Grade "Grade 1" already exists. → inline AppBanner (error) at top + autofocus name field (grade.service.ts:23).

Delete: confirm dialog warns "Sections and classes of this grade will remain but become orphaned" — honest copy; cascade (planned) (OQ-3).

4. Grade Detail /academics/grades/:id

Header: name + code + displayOrder + status; actions Edit/Delete. Sections section: SectionChips (module component) from GET /sections/by-grade/:gradeId — tap chip → section detail; "Add section" → form (section picker pre-filled with this grade). Classes section: client-joined rows from classes cache where gradeId matches; shows which year each belongs to (badge) since grades may float across years (grade.schema.ts:9-10).

5. Classes List /academics/classes

Chrome: AppBar "Classes" + year switcher + filter chips (AppChips): All / This year / Active only (client filter on status).

Row:

• Leading: Icons.groups avatar.
• Title: name (Ty.titleMedium) — e.g. "Grade 10 - A" (create-class.dto.ts:22).
• Subtitle: joined chips "Grade 10 · Section A" + year name; capacity right-aligned mono "40".
• Trailing: status badge; AppMenu (Edit / Delete).

Feed: GET /classes (all) or GET /classes/by-year/:academicYearId when a year is selected (server-filtered, paginated). Both unsorted → preserve order.

Conflicts: duplicate class names per (year, grade, section) are possible (class.service.ts:16-18) — client warns with a tertiary "Duplicate" chip on rows sharing (gradeId, sectionId, name) (OQ-4).

Create (screen 14.3): cascading pickers Year → Grade → Section (13 §2); name auto-suggested "Grade {name} - {section}" (editable).

6. Class Detail — MASTER /academics/classes/:id

Chrome: AppBar back + class name; two tabs: Overview · Subjects & teachers; FAB: on Overview tab = Edit, on roster tab = Add subject+teacher (small FAB morph via AnimatedSwitcher, Mo.m-fast).

Overview tab:

• Header card: name headlineMedium, grade/section/year chips, status badge.
• Meta AppCard: Capacity (mono), Class teacher (name resolved from users cache — classTeacherId is a user ObjectId per create-class.dto.ts:32-35), Room (roomId, free string — render as text, OQ-6), Campus (campusId, opaque id — hide unless resolved, OQ-6).
• Links section (AppListTiles): "Timetable" → /timetable?classId= (timetable.controller.ts:22-29); "Attendance" → attendance module; "Students" → students module ((planned) count from class_enrollments).

Subjects & teachers tab (assignment matrix — module core):

• Roster = GET /subject-assignments/by-class/:classId?academicYearId= (bare array, subject-assignment.controller.ts:24-29).
• Rows: SubjectAssignmentRow — subject name + code chip + shortName, teacher name, trailing AppMenu (Replace / Remove).
• Conflict surface: duplicate subject rows → AppBanner(warning) "Same subject assigned twice" + row highlighted tertiary; empty roster → AppEmptyState compact "No subjects assigned yet" + "Add subject".
• Replace = delete + create (no update endpoint, subject-assignment.controller.ts:19-39); Remove = destructive confirm → DELETE /subject-assignments/:id; stale id → 404 Assignment not found. (subject-assignment.service.ts:34) → treat as already-removed, refresh.

Tablet/desktop (≥ 840 dp): detail pane shows tabs side-by-side with the list pane; roster tab renders as a table (columns: Subject | Code | Teacher | Actions) with column headers announced (00-shared/09 §7).

A11y: tab semantics; each roster row = one Semantics(button) group with action hints; conflict banner in a live region.

7. Section Detail /academics/sections/:id

Header: name headlineMedium, grade chip (joined), status badge. Meta card: Capacity, Class teacher, Room (same resolution rules as class). Classes using this section: client-joined rows (from classes cache where sectionId matches) with year badges. Actions: Edit / Delete (orphan warning on delete — sections are referenced by classes with required sectionId, class.schema.ts:18-19).

8. Sections List /academics/sections

Simple list; rows = section name + grade label chip + capacity; filter chips (All / By grade via GET /sections/by-grade/:gradeId). FAB "Add section" (grade picker first).

9. Subjects List /academics/subjects

Chrome: AppBar "Subjects"; FAB "Add subject"; search via AppSearchBar client-side only (server q unused — OQ-7 in 01).

Row:

• Leading: Icons.menu_book.
• Title: name; subtitle: code mono + shortName if set.
• Trailing: marks summary bodySmall "100 max · pass 33" (admin/coordinator only — hidden for P4) + status badge + AppMenu.

Ordering: insertion order (subject.service.ts:35-47); no reorder field exists — client preserves.

10. Subject Detail /academics/subjects/:id

Header: name + code chip + shortName + status. Marks card (AppCard): grid of four stat tiles — Maximum, Passing, Theory, Practical (Ty.titleMedium numerals with tabularFigures(), 00-shared/02 §2); values from subject.schema.ts:21-32. Edit → form without theory/practical fields (not updatable — update-subject.dto.ts:4-42; flagged, OQ-5). Usage section: "Assigned to N classes" — client-joined count from cached rosters; rows link to class detail.

11. Subject Assignment Matrix (full screen) /academics/classes/:id/assign

Full-screen sheet (≥ 3 fields, 00-shared/05 §5):

• Header: class name + year.
• Existing rows (same SubjectAssignmentRow as §6).
• "Add" opens AppBottomSheet (2/3 height):
  • AppDropdown Subject (searchable) — pre-loaded catalog; entries already assigned to this class are disabled with "Already assigned" note.
  • AppDropdown Teacher (searchable) — user pickers filtered to teacher roles (Users module); (planned) server-side teachers list.
  • CTA "Assign" → POST /subject-assignments {teacherId, subjectId, classId, academicYearId} (all IsMongoId, create-subject-assignment.dto.ts:5-19).
• Conflict: if server someday returns 409/422 → banner; today server never rejects duplicates (OQ-4) — client guard only.

12. Hierarchy Explorer /academics/explore

Chrome: AppBar "Structure"; year switcher; search box (client filter on names). Layout:

• HierarchyTree (module component, 07 §1): root = Year → children = Grades → Section → Class leaves; each node shows counts (sections/classes/subjects).
• Expand/collapse with AnimatedSize (Mo.m-base); default: years expanded, grades collapsed.
• Leaf tap → class master screen; node context menu (Edit / Add child) for admin/coordinator. Gap spotting (coordinator): nodes with 0 children get a tertiary dot + "empty" label; class nodes without subjects get a warning badge. Data: composed client-side from the 4 list endpoints (no tree endpoint exists) — see 15_Flutter_Implementation_Guide.md §4.

13. Teacher Roster /academics/teachers/:teacherId

Chrome: AppBar teacher name; year switcher (query academicYearId). Rows: class name + subject (+ code), grouped by class (List.groupBy, 00-shared/11 §8). Conflict: same subject in ≥ 2 classes → AppBanner(warning)

• row highlights. Empty: "No teaching load this year". Data: GET /subject-assignments/by-teacher/:teacherId?academicYearId= (subject-assignment.controller.ts:30-35).

Interaction & motion summary (module)

Keyboard (desktop)

N = new on list screens; Ctrl+Enter = submit forms / set-current; Esc = close sheets/dialogs; Tab logical order Year→Grade→Section→Class→Subject (00-shared/08 §2).

07 — Component Library (Academics Module)

• 1. HierarchyTree
• 2. SectionChips
• 3. SubjectAssignmentRow
• 4. YearStatusBadge
• 5. EntityStatusBadge (grade/section/class)
• 6. CascadingEntityPicker
• 7. MarksSummaryTiles
• 8. RosterTable (desktop)
• 9. ConflictBanner
• 10. ReferenceCacheProvider (infra widget)
  • Dependency map

Module-specific widgets. Shared components (00-shared/03) are referenced by name and used as-is (AppCard, AppListTile, AppDropdown, AppChips, AppSearchBar, AppSkeleton, AppEmptyState, AppErrorState, AppBanner, AppSnackbar, AppDialog, AppDatePicker, AppTextField, AppMenu, AppFAB). All names are proposals; the server API facts they bind to are exact.

1. HierarchyTree

• Purpose: renders the Year → Grade → Section → Class structure as an expandable tree (Hierarchy Explorer, 06 §12).
• Props: nodes (nested model: year → grades → sections → classes), expandedIds: Set<String>, onToggle(id), onNodeTap(node), onNodeMenu(node) (admin), highlightEmpty: bool.
• States: loading (AppSkeleton rows), empty (root AppEmptyState), error (AppErrorState), expanded/collapsed.
• Row anatomy: leading expand icon (rotates Mo.m-fast), depth indent Sp.8 × level, entity icon by type, title Ty.titleMedium, subtitle counts bodySmall onSurfaceVariant ("4 sections · 8 classes"), trailing status badge / warning dot (empty node, tertiary).
• A11y: each node Semantics(expanded:) + label "Grade 10, expanded, 4 sections"; keyboard arrows expand/collapse (00-shared/09 §6).
• Tokens: node hover surfaceVariant; expanded child indent guides outlineVariant 1 px; Flutter: custom ExpansionTile-free AnimatedSize list (keep N expanded ≤ 50 for perf, lazy-load children).

2. SectionChips

• Purpose: dense list of a grade's sections (Grade detail, 06 §4; class rows).
• Props: sections[{id,name,capacity,status}], selectedId?, onTap, maxChips (default 8 → "+N more").
• States: default, selected (secondaryContainer), inactive (status ≠ 'active' → outlined + strike-through name, OQ-2), overflow.
• A11y: Semantics(label: "Section A, capacity 40"); chip group labeled.
• Flutter: Wrap of FilterChip/InputChip (00-shared/04 §2).

3. SubjectAssignmentRow

• Purpose: one row in the roster / matrix (06 §6, §11).
• Props: subject{code,name,shortName}, teacherName, conflict: bool, onReplace, onRemove, readOnly.
• Anatomy: leading subject avatar (Icons.menu_book, primaryContainer when conflict → tertiaryContainer), title subject.name, subtitle code mono + shortName, trailing teacher name bodyMedium + AppMenu (Replace/Remove).
• Conflict state: tertiary left border 2 px + warning icon + tooltip "Assigned more than once" (client-computed — server allows duplicates, OQ-4).
• A11y: whole row one Semantics(button) with subject + teacher label.
• Flutter: ListTile-custom with AnimatedContainer border.

4. YearStatusBadge

• Purpose: status chip for academic_years.
• Props: status: 'upcoming'|'active'|'archived', isCurrent: bool.
• Mapping: upcoming → outline chip; active → tonal (primaryContainer); archived → neutral (surfaceVariant); isCurrent adds a filled primary pill "Current" (rendered separately, see 06 §1).
• Source: enum AcademicYearStatus (academic-year.schema.ts:7-11).

5. EntityStatusBadge (grade/section/class)

• Purpose: status chip for entities whose schema status is a free string (default 'active').
• Behaviour: status === 'active' → no badge (default, reduces noise) or subtle tonal "Active"; anything else → neutral "Archived"-style badge with the raw value truncated.
• Source: grade.schema.ts:21-22, section.schema.ts:24-25, class.schema.ts:33-34; flag OQ-2 (01).

6. CascadingEntityPicker

• Purpose: Year → Grade → Section cascading dropdown group (Class create form, 06 §5; also Grade → Section standalone).
• Props: scopedYearId, onYearChanged, grades, sections (already filtered by the parent selection via the ReferenceRepository, 13 §2), onChanged(selection), errorText, readOnly.
• Behaviour: parent cleared → children reset + disabled; selections emit a complete {academicYearId, gradeId, sectionId} or null.
• A11y: group Semantics; each dropdown role "combobox"; errors announced.
• Flutter: three AppDropdown in a column with AnimatedSize validation reveal.

7. MarksSummaryTiles

• Purpose: read-only 4-tile grid for subject marks config (Subject detail, 06 §10).
• Props: maximumMarks, passingMarks, theoryMarks, practicalMarks.
• Anatomy: 2×2 grid of AppCard-tiles; label labelMedium, numeral Ty.titleMedium with tabularFigures().
• A11y: one group labeled "Marks configuration", each value announced.
• Source: subject.schema.ts:21-32 defaults (100/33/80/20).

8. RosterTable (desktop)

• Purpose: table variant of the assignment matrix ≥ 840 dp (06 §6).
• Props: rows, onReplace, onRemove, readOnly.
• Anatomy: columns Subject | Code | Teacher | Actions; sticky header (surfaceContainerLow), column headers announced; row hover surfaceVariant.
• Flutter: DataTable wrapped with Scrollbar (always visible on desktop, 00-shared/04 §8).

9. ConflictBanner

• Purpose: inline warning for client-computed conflicts (duplicate assignment, empty class, orphan node).
• Props: kind: duplicate|empty|orphan|teacherOverlap, message, action?.
• Tokens: tertiaryContainer background, onTertiaryContainer text, r-md; slide-down + fade Mo.m-base; live region.
• Flutter: custom MaterialBanner-style AnimatedContainer (not AppBanner error — conflicts are warnings, not errors).

10. ReferenceCacheProvider (infra widget)

• Purpose: top-of-tree widget exposing the 24 h reference cache (13 §3) to all Academics screens.
• Props: tenantId, yearId scope; exposes years, grades, sections, classes, subjects + refreshAll().
• Behaviour: invisible; drives RefreshIndicator cascades; emits ReferenceChanged so timetable/attendance screens re-fetch their scoped lists (13 §5).
• Flutter: InheritedNotifier over the ReferenceCubit.

Dependency map

08 — Form Specifications (Academics Module)

• 1. Academic Year — Create (POST /academic-years)
• 2. Academic Year — Update (PATCH /academic-years/:id)
• 3. Grade — Create (POST /grades)
• 4. Grade — Update (PATCH /grades/:id)
• 5. Section — Create (POST /sections)
• 6. Section — Update (PATCH /sections/:id)
• 7. Class — Create (POST /classes)
• 8. Class — Update (PATCH /classes/:id)
• 9. Subject — Create (POST /subjects)
• 10. Subject — Update (PATCH /subjects/:id)
• 11. Subject Assignment — Create (POST /subject-assignments)
• Shared submission behaviour (all forms)

Field-by-field specs for every create/update form. Field metadata (required, type, validation, defaults) is exact from src/modules/academics/dto/*; server validation via class-validator (ValidationPipe → 400 VALIDATION_ERROR with per-field details, 00-shared/07 §3). Shared form rules: full-screen page (> 3 fields), submit button loading state (anti-double-submit), errors inline per field + focus first invalid, offline → blocked with banner (00-shared/08 §6, 00-shared/10 §2). Dates: IsDateString = ISO-8601 YYYY-MM-DD (swagger examples, create-academic-year.dto.ts:9-15).

1. Academic Year — Create (POST /academic-years)

Fields exact from create-academic-year.dto.ts:4-21:

• Success: 200 doc → navigate to detail; snackbar "Year created".

2. Academic Year — Update (PATCH /academic-years/:id)

From update-academic-year.dto.ts:4-28: all optional — name, startDate, endDate, status, isCurrent (bool).

• UI rule: isCurrent is not shown as a normal checkbox — edits use "Set as current" on the list/detail (PATCH /:id/set-current, academic-year.service.ts:69-83) which also forces status: active. Inline checkbox would fight that; keep the dedicated action.
• Server sets only provided fields ($set, academic-year.service.ts:64).

3. Grade — Create (POST /grades)

From create-grade.dto.ts:4-24:

• Success → list refresh (keeps displayOrder sort, grade.service.ts:39).

4. Grade — Update (PATCH /grades/:id)

From update-grade.dto.ts:4-30: all optional — academicYearId, name, code, displayOrder, status. status shown only for admin; free-string field with a suggested picker of active / archived (schema default 'active', grade.schema.ts:21-22; OQ-2 01).

5. Section — Create (POST /sections)

From create-section.dto.ts:4-28:

6. Section — Update (PATCH /sections/:id)

From update-section.dto.ts:4-35: all optional — gradeId, name, capacity, classTeacherId, roomId, status. Reparenting caution: changing gradeId orphans classes referencing this section (class.schema.ts:18-19 required) — client shows confirm "Classes of this section keep pointing at it".

7. Class — Create (POST /classes)

From create-class.dto.ts:4-41:

• No uniqueness on (academicYearId, gradeId, sectionId, name) (class.service.ts:16-18) — client shows a "Duplicate class?" confirm when the exact combo already exists in cache (OQ-4).

8. Class — Update (PATCH /classes/:id)

From update-class.dto.ts:4-50: all optional — academicYearId, campusId, gradeId, sectionId, name, capacity, classTeacherId, roomId, status. Same reparenting caution as section (below, §6).

9. Subject — Create (POST /subjects)

From create-subject.dto.ts:4-47:

• Client cross-validation (server has none — OQ-5 01): theoryMarks + practicalMarks ≤ maximumMarks; passingMarks ≤ maximumMarks; error under the offending field, block submit.

10. Subject — Update (PATCH /subjects/:id)

From update-subject.dto.ts:4-42: all optional — code, name, shortName, credits, maximumMarks, passingMarks, status. theoryMarks / practicalMarks are NOT updatable — do not render those fields in edit mode; add a helper line "Theory/Practical marks locked (planned)" (OQ-5). code change → 409 if taken (service checks only on create; a duplicate code update is not checked and will hit the unique index → 500-mapped 409 by the exception filter — client surfaces as "Code already in use" on 409/5xx DUPLICATE per http-exception.filter.ts mapping; flag OQ-2 01).

11. Subject Assignment — Create (POST /subject-assignments)

From create-subject-assignment.dto.ts:4-20:

No update form (no endpoint) — "Replace" flow = confirm dialog → DELETE /subject-assignments/:id → reopen create sheet.

Shared submission behaviour (all forms)

• Submit → button loading (label replaced, 00-shared/08 §6); fields disabled.
• 400 → per-field errorText from error.details[] (field names match DTO keys); focus first invalid.
• 401 → silent refresh then retry once; fail → sessionExpired.
• 409 → inline AppBanner(error) with server message (name/code conflicts).
• 429 → countdown banner; no auto-retry (00-shared/07 §4).
• 5xx → generic error + requestId (never server internals).
• Success → snackbar + navigate (list or detail per entity); no optimistic write (server returns canonical doc — reconcile from response).

09 — User Behaviour (Academics Module)

• 1. Expected behaviour (server-contract-driven)
• 2. Common mistakes & countermeasures
• 3. Power & new users
• 4. Mobile & a11y users
• 5. Interrupted sessions & retries
• 6. Abandonment
• 7. Frustration points → UX treatments (summary)
• 8. Cross-device & conflict
• 9. Adoption path (holistic)

Expected behaviour derived from server semantics (src/modules/academics/services/*)

• shared interaction rules (00-shared/08), the common mistakes users make with structure data, and the UX countermeasures. Purpose: a playbook of what the user does so the flows never surprise.

1. Expected behaviour (server-contract-driven)

• Duplicates are rejected by name/code, never silently merged: creating a year or grade with an existing name, or a subject with an existing code, returns 409 DUPLICATE_RESOURCE with exact server copy ("Academic year "X" already exists.", academic-year.service.ts:25-29; grade.service.ts:21-23; subject.service.ts:21-25). The client must never pre-empt with its own copy — render the server message verbatim.
• set-current is a global, one-way-ish flip: PATCH /academic-years/:id/set-current clears isCurrent on every other year, then sets the target isCurrent:true and status:"active" (academic-year.service.ts:69-83). The old current year does not go to archived automatically — it stays active minus the flag. Users expect "old year becomes archived"; the UI must show the real result.
• Delete is soft and silent to children: grade/section/class/assignment delete = softDelete (base.repository.ts:68-74); lists simply stop showing the row. Nothing cascades — sections/classes/assignments pointing at a deleted grade remain in the DB and keep appearing in other lists (OQ-3).
• Correction of an assignment is delete + recreate: there is no assignment update endpoint (subject-assignment.controller.ts:19-39); a wrong teacher is fixed by removing the row and adding a new one.
• Ordering is server-given, not user-sortable: grades render in displayOrder asc (grade.service.ts:37-39); years newest-first (createdAt:-1, academic-year.service.ts:45-47); classes/sections/subjects in insertion order (class.service.ts:41-53, section.service.ts:41-48, subject.service.ts:35-47). Reordering grades = editing displayOrder (int ≥ 0), not drag-and-drop (until a reorder endpoint exists — (planned)).
• q (global search) is accepted but ignored: PaginationQueryDto.q (pagination-query.dto.ts:26-29) is parsed on every list endpoint but no academics service filters on it (services filter {}, e.g. grade.service.ts:41-43). Users will type in a search box and get full lists — client search must be local.
• Grade/section/class status is an open string (default 'active', grade.schema.ts:21-22, section.schema.ts:24-25, class.schema.ts:33-34); only academic-year status is an enum (upcoming|active|archived, academic-year.schema.ts:7-11). Treat any non-active value as inactive.

2. Common mistakes & countermeasures

3. Power & new users

• Power user (admin/coordinator, desktop): keyboard N = new entity on list screens, Ctrl+Enter = submit; year switcher keyboard shortcut; bulk-skip pattern in ladder setup (create Grade 1 → "Save & new" stays in form, displayOrder auto-incremented).
• New user (fresh tenant): first-run empty states chain — create year → create grades → create sections → create classes → assign subjects. Each AppEmptyState CTA navigates the next step; a mini checklist ("Step 2 of 5") helps structure-first onboarding (proposed).

4. Mobile & a11y users

• One-thumb phone: all admin forms are full-screen with the primary CTA at the bottom (thumb zone); the year switcher and filter chips stay within the top ⅓.
• TalkBack/VoiceOver: tree nodes announce level + counts ("Grade 10, expanded, 4 sections"); chips announce full labels ("Section A, capacity 40"); conflict banners read in a live region.
• Dynamic type 200%: chips and status badges wrap (no fixed widths); SectionChips overflow falls back to "+N more" (07 §2).
• Reduced motion: no shake on validation; errors = color + icon + text (00-shared/08 §4).

5. Interrupted sessions & retries

• App killed mid-create form: form state lost (memory only) → return = fresh form; cached lists still available (13 §3) so the user can re-check duplicates.
• Server 5xx on create: generic error + requestId; form values preserved; suggest retry. Duplicate re-submit risk: a 409 "already exists" then means the first attempt actually succeeded — the client should offer "Open existing".
• 401 mid-flow: silent refresh → replay once → sessionExpired → re-login, in-progress form preserved in memory.
• 429: countdown banner, no auto-retry (00-shared/07 §4).

6. Abandonment

7. Frustration points → UX treatments (summary)

8. Cross-device & conflict

• Two admins editing the same structure: last-write-wins — every doc carries a version counter incremented per update (base.repository.ts:57-66) but the client does not send it (PATCH bodies are plain $set DTOs, update-class.dto.ts:4-50); no 409/412 optimistic-concurrency errors surface. UI: refresh lists on focus; treat remote changes as truth.
• set-current raced from two devices: both PATCHes run sequentially server-side; the later one wins — the client re-reads the years list after the call to render the true current year.

9. Adoption path (holistic)

P0 (backend already complete): structure browse + create/edit for admin. P1: teacher roster, student browse, conflict UX. P2 (planned): server-side search (q), conflict/duplicate validation, cascade jobs (RELATIONSHIPS.md:134-138), coaching extension (docs/IMPLEMENTATION_PLAN.md §6.2.1).

10 — Interaction Specification (Academics Module)

• 1. Phone / touch
• 2. Keyboard / desktop / mouse
• 3. Haptics (mobile)
• 4. Motion language (module extension of 08 §4)
• 5. Micro-interactions catalogue
• 6. Frustration controls (shared 08 §6 + module)
• 7. Special: deep-link & clipboard interactions
• 8. Validation of interaction to server semantics

Module-specific interactions for hierarchy browsing, master-detail, cascading pickers, and the assignment matrix, layered on shared 00-shared/08. Covers phone/tablet/desktop. Every interaction stays within server semantics (no optimistic writes on deletes/set-current).

1. Phone / touch

2. Keyboard / desktop / mouse

3. Haptics (mobile)

4. Motion language (module extension of 08 §4)

Reduced-motion: all of the above degrade to fades ≤ m-instant; no slide or scale.

5. Micro-interactions catalogue

6. Frustration controls (shared 08 §6 + module)

• All presses respond < 100 ms with m-fast ripple.
• Every network action shows pending state (button loading / skeleton / spinner).
• Submit disabled while pending — no double-submit (anti-double-create: the worst failure here is a duplicate 409 that actually succeeded on the server).
• 429 → countdown, never auto-retry.
• Errors persist until corrected or dismissed; conflict banners stay until resolved (not auto-timeout) since they change the meaning of the roster.

7. Special: deep-link & clipboard interactions

• studylyon://academics/classes/:id → class master screen directly.
• studylyon://academics/explore?yearId= → explorer scoped to a year.
• ObjectId paste: admin/dev build accepts pasted MongoId in search fields to jump to an entity (hidden behind kDebugMode flag).
• Roster table (desktop): SelectableText on code/IDs, Ctrl+C works.

8. Validation of interaction to server semantics

11 — Design System Mapping (Academics Module)

• 1. Theme recipes (module)
• 2. Widget → token
• 3. Typography mapping
• 4. Iconography
• 5. Motion tokens (values 00-shared/02 §6)
• 6. Contrast & dark parity
• 7. Breakpoint behaviour

Academics module → Material 3 / Flutter / token mapping, extending 00-shared/04. Every color, type, spacing, elevation, radius, icon, motion reference traces to 00-shared/02_Design_Tokens.md. Module components defined in 07_Component_Library.md.

1. Theme recipes (module)

2. Widget → token

3. Typography mapping