04 — Information Architecture (Reports Module)
- 1. Module subtree
- 2. Core objects
- 3. State model per object
- 4. Navigation rules
- 5. Module boundaries (what Reports does NOT own)
How report content is organized in the app. Global structure per 00-shared/05; this file defines the Reports subtree, its objects and states.
1. Module subtree
Reports (module root)
├── Catalog → report type templates (static list, client-defined)
├── Generate → form for one selected template
├── Job list → my tenant's recent jobs (server: `report_jobs` collection)
├── Job detail → status + progress + result of one job
└── Result view → rendered result data / file open `(planned)`
Routes (Flutter, (recommended) — see 15):
/reports, /reports/new, /reports/jobs, /reports/jobs/:jobId,
/reports/jobs/:jobId/result.
2. Core objects
Report type (template)
Static client catalog mirroring the server enum (report-job.schema.ts:7-11):
| Type | Label | Params | Result shape |
|---|---|---|---|
report_card | Report card | studentId, examId (both required by service — reports.service.ts:91) | {studentName, studentId, examId, generatedAt, subjects[], totalMarksObtained, totalMaximumMarks, percentage, grade} (reports.service.ts:96-107) |
attendance_summary | Attendance summary | classId?, startDate?, endDate? (generate-report.dto.ts:17-33) | {total, summary:{status→count}, classId, period:{startDate,endDate}} (reports.service.ts:131-136) |
fee_summary | Fee summary | none (reports.service.ts:140) | {totalInvoices, totalCollected, totalPending, totalOverdue} (reports.service.ts:154-158) |
(planned) types from docs/IMPLEMENTATION_PLAN.md:646: BATCH_PERFORMANCE,
TEST_SERIES_ANALYSIS, DPP_COMPLETION (coaching).
Report job
Server document (report-job.schema.ts:21-43), collection report_jobs:
| Field | Type | Notes |
|---|---|---|
type | enum | required (:22-24) |
status | enum | default queued (:25-30) |
params | object | echo of request (:32-33) |
result | object | set on completion (:35-36) |
error | string | set on failure (:38-39) |
completedAt | date | set on completion (:41-42) |
| + BaseSchema | tenantId, createdAt, updatedAt, version, … (base.schema.ts) |
Indexes: {tenantId, status} and {tenantId, createdAt:-1}
(report-job.schema.ts:47-48) → job list is sorted by recency.
3. State model per object
ReportType: static
ReportJob: queued | processing | completed | failed (server enum, :13-18)
Result: pending | ready | missing (result absent even when completed — possible
for zero-record summaries; treat as ready-empty)
File: not yet | attaching (planned) | streaming (planned) | done | failed
4. Navigation rules
- Job detail is the single hub — reached from job list, from post-submit
redirect, and (future) from notification deep link
(forward-looking). - Result view opens from job detail only when
status == completed. - Catalog → Generate is the only forward path that creates a job.
- No cross-module entry today; students module "report card" shortcut
(forward-looking)— prefill comes from student profile context.
5. Module boundaries (what Reports does NOT own)
- Files/attachment storage →
filesmodule (GET /files/:id/download,files.controller.ts:55-64) once PDF export lands(planned). - Scheduler definitions →
schedulermodule (AttendanceReportJob,attendance-report.job.ts:4-7). - Notifications →
ReportGeneratedevent(planned); queue map has no report route today (event-queue-map.ts). - Data sources (students/attendance/fees/results) — read-only, injected via
modules (
reports.module.ts:20-23).