05 — Screen Inventory (Dashboard Module)
- Legend
- 1. Dashboard Home (
/dashboard) - 2. Attendance Detail (
/dashboard/attendance)(planned) - 3. Finance Detail (
/dashboard/finance)(planned) - 4. Widget Customization (
/dashboard/customize)(planned) - Shared components used
- Analytics events
(proposed) - Keyboard, landscape, tablet, desktop
Every dashboard screen, its intent, route, composition, states, permissions, platform behaviour and events. Authoritative components in 00-shared/03; this file enumerates which ones each screen uses with module specifics.
Legend
States = idle / loading / success / empty / error(offline, rate, invalid) /
disabled / permission. Analytics events follow {module}.{screen}.{action}
(proposed); SDK open (00-shared/10 §8). Endpoints per 12_API_Mapping.md.
1. Dashboard Home (/dashboard)
| Field | Detail |
|---|---|
| Purpose | Role-filtered operational KPIs at a glance, from one cached endpoint |
| Entry | Post-login landing (roles with dashboard.read); any app navigation |
| Exit | drill-through to Students/Fees/Attendance; (planned) customize |
| Source | GET /api/v1/dashboard/overview (dashboard.controller.ts:13-17) → dashboard.service.ts:50-70 payload |
| Composition | KPI row (students/teachers/staff counts + attendance % + finance dues) (planned) chart blocks; (planned) widget grid |
| Permission | dashboard.read required (permissions.constants.ts:37); only org_admin has it by default (role.schema.ts:23) — no-permission → module not reachable, never a 403 dead-end |
| States | loading (skeletons), success, empty (zero counts — dashboard.service.ts:64 rate 0 path), error (offline/5xx with retry), stale (TTL badge) |
| Realtime | WS tenant:{id} room events (ws.gateway.ts:50; ws-bridge.service.ts:16-22) → invalidate + refetch for the 4 KPI events (Dashboard.md:34) |
| Analytics | dashboard.overview.open, dashboard.kpi.tap, dashboard.refresh (proposed) |
2. Attendance Detail (/dashboard/attendance) (planned)
| Field | Detail |
|---|---|
| Purpose | Attendance rate trend over a period |
| Source | GET /api/v1/dashboard/attendance (Dashboard.md:24) — no controller today |
| Composition | Period selector (planned); line/bar chart (AppCharts, 00-shared/03); today's summary (dashboard.service.ts:40-43) |
| Permission | dashboard.read; teacher-scoped variant (planned) (IMPLEMENTATION_PLAN.md:232) |
| States | as §1; empty = "no attendance yet" (rate 0 path :64) |
3. Finance Detail (/dashboard/finance) (planned)
| Field | Detail |
|---|---|
| Purpose | Pending invoices + dues trend |
| Source | GET /api/v1/dashboard/finance (Dashboard.md:25) |
| Composition | dues number, pending-invoice count, collection trend chart; drill to /fees/invoices |
| Permission | dashboard.read; accountant role (planned) (has fees.collect role.schema.ts:47, lacks dashboard.read) |
| States | as §1 |
4. Widget Customization (/dashboard/customize) (planned)
| Field | Detail |
|---|---|
| Purpose | Admin reorders/toggles widgets per tenant |
| Source | GET /api/v1/dashboard/widgets, PATCH /api/v1/dashboard/widgets/:id (Dashboard.md:26-27); persistence in dashboard_widgets (Dashboard.md:7) |
| Permission | dashboard.widget.manage (permissions.constants.ts:38) — server API absent, entry hidden until it ships |
| Composition | widget palette (reorder handles, visibility toggles, role chips (planned)) |
| States | as §1 + saving (per-widget pending), conflict (concurrent edit) |
Shared components used
AppCard, AppSkeleton, AppEmptyState, AppErrorState, AppRefreshIndicator,
AppOfflineBanner, AppSnackbar, AppBadge, AppChips, AppCharts
(00-shared/03). Module-specific: KpiCard, TrendIndicator, ChartCard,
StaleBanner, WidgetPalette (planned) — defined in 07_Component_Library.md.
Analytics events (proposed)
dashboard.overview.{open,refresh,stale}, dashboard.kpi.{tap,drill},
dashboard.attendance.{open,period},
dashboard.finance.{open,period},
dashboard.widgets.{open,reorder,toggle,save}.
Keyboard, landscape, tablet, desktop
- Phone: single-column scroll; KPI row horizontal-scroll; landscape scrolls.
- Tablet (≥840 dp): two-column KPI grid + chart side-by-side.
- Desktop: full widget grid (max 3 columns), hover on KPI cards reveals drill affordance.
- No text input anywhere → keyboard concerns only for
(planned)customize search field.