04 — Information Architecture (Fees Module)
- 1. Zone: authenticated app → Fees destination
- 2. Route table (module-owned)
- 3. Screen hierarchy
- 4. Modal hierarchy (per
00-shared/05 §5) - 5. Screen relationships
- 6. Quick actions / FAB / context menus
- 7. Information needs per screen (content model)
- 8. Accessibility of IA
Zones, routes, hierarchy, modals, content model. Route table extends 00-shared/05. Backend contract sources:
fees.controller.ts:21-81,payments.controller.ts:17-73.
1. Zone: authenticated app → Fees destination
Fees lives under the authenticated shell (bottom nav / rail, 00-shared/05 §2). Owner of: structures, invoices, payment recording, dues. Payments-v2 (online) screens (transaction list, receipt viewer) are shared with the payments module.
2. Route table (module-owned)
| Route | Screen | Backend | Source |
|---|---|---|---|
/fees | Fees home (dues summary + quick actions) | GET /fees/dues | fees.controller.ts:76-80 |
/fees/structures | Fee structures list | GET /fees/structures | fees.controller.ts:34-38 |
/fees/structures/new | Create structure | POST /fees/structures | fees.controller.ts:28-32 |
/fees/structures/:id | Structure detail | GET /fees/structures/:id | fees.controller.ts:40-44 |
/fees/structures/:id/edit | Edit structure | PATCH /fees/structures/:id | fees.controller.ts:46-50 |
/fees/students/:studentId/invoices | Student invoices | GET /fees/students/:studentId/invoices | fees.controller.ts:64-68 |
/fees/invoices/:id | Invoice detail | (compose: student invoices + GET /payments/invoice/:id) | payments.controller.ts:57-61 |
/fees/invoices/:id/pay | Record payment (till) | POST /fees/invoices/:id/payments | fees.controller.ts:70-74 |
/fees/dues | Dues list | GET /fees/dues | fees.controller.ts:76-80 |
/fees/dues/report | Dues report (proposed) | client-side aggregation | — |
/payments/:transactionRef | Payment detail (v2) | GET /payments/:id | payments.controller.ts:51-55 |
/payments/receipts/:id | Receipt view/print | GET /payments/receipts/:id | payments.controller.ts:69-73 |
/fees/reminders | Reminders (planned) | none (no endpoint) | fee-reminder.job.ts:16-46 |
3. Screen hierarchy
Fees (/fees)
├── Dues (default landing) /fees/dues
│ └── Invoice detail /fees/invoices/:id
│ ├── Record payment /fees/invoices/:id/pay
│ └── Receipt view /payments/receipts/:id (after payment)
├── Fee structures /fees/structures
│ ├── Create /fees/structures/new
│ └── Detail /fees/structures/:id
│ ├── Edit /fees/structures/:id/edit
│ └── Generate invoice (dialog → POST invoices/generate)
├── Student invoices /fees/students/:studentId/invoices → invoice detail
└── Payments (online) — shared with Payments module
├── Transaction list /payments
└── Receipts list /payments/receipts
4. Modal hierarchy (per 00-shared/05 §5)
- Generate invoice dialog (from structure detail): student picker + optional
discounts list →
POST /fees/invoices/generate— 409 handled inline. - Record payment sheet (from invoice detail or dues row): amount, method,
reference, date, notes —
POST /fees/invoices/:id/payments; idempotency key generated client-side per attempt (record-payment.dto.ts:31-34). - Delete structure confirm dialog: soft-delete note ("Existing invoices are
kept"),
DELETE /fees/structures/:id(fees.service.ts:95-98). - Receipt print sheet (
(proposed)): renders the receipt doc, share via share-sheet / print. - Refund dialog (payment detail, v2): amount + reason →
POST /payments/refund(payments.controller.ts:30-34).
5. Screen relationships
| From | Action | To |
|---|---|---|
| Dues row | tap | Invoice detail |
| Dues row | "Collect" | Record payment sheet |
| Structure detail | "Generate invoice" | Generate invoice dialog |
| Invoice detail | "View receipt(s)" | Receipt view |
| Invoice detail (unpaid) | "Pay online" (forward-looking) | Payments module flow |
| Invoice detail | "Payment history" | GET /payments/invoice/:id rows |
6. Quick actions / FAB / context menus
- Fees home: FAB "Collect payment" → scan/select student
(forward-looking)or dues row → record payment sheet. - Structures list: FAB "New structure"; row menu Edit / Duplicate
(
(planned)IMPLEMENTATION_PLAN.md:205) / Delete. - Invoice detail: menu: Refresh, Print/Share receipt
(proposed), (v2) Refund. - Dues screen: filter chips by status (
issued|partial|overdue— the exact set the server queries,fees.service.ts:190-212).
7. Information needs per screen (content model)
- Structure doc (
fee-structure.schema.ts:8-38+BaseSchema):_id, tenantId, name, classId, academicYearId, items[{name,amount}], totalAmount, currency, dueDate, lateFee, isActive, createdAt, updatedAt, version, isDeleted…(base.schema.ts:8-35). - Invoice doc (
invoice.schema.ts:16-51):_id, studentId, feeStructureId, academicYearId, totalAmount, paidAmount, status, dueDate, issuedAt?, discounts[], createdAt…. - Payment doc (fees) (
fees/schemas/payment.schema.ts:22-55):_id, invoiceId, amount, paymentMethod, reference?, idempotencyKey, paidAt, notes?, status(alwayscompletedtoday). - Payment doc (v2) (
payments/schemas/payment.schema.ts:28-77):transactionReference, amount, fee, refundedAmount, currency, gateway, gatewayTransactionId?, gatewayResponse?, status, invoiceId?, invoiceType?, payerId?, payerEmail?, payerName?, description?, metadata?. - Receipt doc (
receipt.schema.ts:7-41):receiptNumber, paymentId, invoiceId?, amount, fee, currency, paymentMethod, payerName?, payerEmail?, description?, issuedAt. - Dues row (
fees.service.ts:213-216):{invoice: InvoiceDoc, due: number}—due = totalAmount − paidAmount.
8. Accessibility of IA
- Every list screen reachable in ≤ 3 taps from
/fees; FABs duplicated as menu items on desktop. - Status is always text + color (never color-only;
09 §9). - Money rendered with currency symbol +
tabularFigures(02 §2 mono). - Deep links
(proposed):studylyon://fees/dues,studylyon://fees/invoices/:id,studylyon://payments/receipts/:id.