04 - Information Architecture (Houses Module)
- 1. Navigation tree
- 2. Entity map
- 3. Object model (client)
- 4. Cross-module relations
- 5. Content hierarchy (house detail)
- 6. IA gaps (flagged)
Where Houses sits in the app information architecture. Global IA rules live in 00-shared/05 (Global Information Architecture); this file defines the Houses subtree only. Server truth:
houses.controller.ts:17-20(/housesroot, JWT-guarded,ApiTags('houses')).
1. Navigation tree
Settings / Organization (parent: School setup)
└── Houses (/houses) houses.read
├── House list (/houses)
├── House detail (/houses/:id) members section (planned server-side)
└── House editor (bottom sheet / dialog - NOT a route, per 00-shared/03)
Student module (assignment lives here, not in Houses)
└── Student detail (/students/:id) -> house chip -> House detail (deep link back)
- House create/edit is a bottom sheet (phone) / dialog (tablet), consistent with
00-shared/03- forms are never routes (see15§7). - House detail is the only deep-linkable page:
/houses/:id.
2. Entity map
| Entity | Fields | Source |
|---|---|---|
| House | name*, code*, color?, motto? + BaseSchema (tenantId, createdBy/updatedBy, isDeleted/deletedAt/deletedBy, version, createdAt/updatedAt) | house.schema.ts:9-19, base.schema.ts:8-34 |
| Student (relation only) | houseId? → ref: 'House' (ObjectId, optional) | student.schema.ts:41-42 |
| Pagination meta | page, limit, totalItems, totalPages, hasNext, hasPrevious | pagination-query.dto.ts:32-39 |
3. Object model (client)
class House {
final String id; // Mongo ObjectId string
final String name; // required, trimmed server-side
final String code; // required, trimmed; unique per tenant
final String? color; // free string - semantic token mapping in 11
final String? motto;
final DateTime? createdAt;
final DateTime? updatedAt;
final int version; // optimistic-lock counter (base.schema.ts:30-31)
}
Never send tenantId / isDeleted / version in requests - server-owned
(base.schema.ts:10-11, 20-21, AGENTS.md).
4. Cross-module relations
| Relation | Mechanism | Source |
|---|---|---|
| House ← Student | student.houseId ObjectId ref (no populate in students service) | student.schema.ts:41-42 |
| House → members | None server-side. Client joins GET /students (filtered) with house list; (planned) filter/members endpoint | 09 §G1, 12 §8 |
| House → staff (house master) | None. Field (planned) | 01 §4.2 |
| House → events (points) | None. (planned) / (forward-looking) | 01 §4.2-4.3 |
5. Content hierarchy (house detail)
- Identity block - color banner, name, code chip, motto.
- Members - count + list (client-joined today;
(planned)GET /houses/:id/members). - Meta - createdAt / updatedAt / version (admin-only, small print).
6. IA gaps (flagged)
- Members live under Students IA but are displayed under Houses - needs a server
bridge (
(planned)houseId filter on students list). - No search/filter on the houses list (
q/sortexist inPaginationQueryDtobut houses list ignores them -houses.service.ts:30).