Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

12 - API Mapping (Houses Module)

Exact wire contracts for the Houses module. Base path /api/v1 (URI versioning, main.ts); all endpoints JWT-guarded (houses.controller.ts:19-20), tenant-scoped via HouseRepository → BaseRepository (house.repository.ts:9-15). Envelopes per 00-shared/07 §2-3. Permissions from permissions.constants.ts:46-49 (RBAC guards on endpoints not yet wired - AGENTS.md).

1. Houses (houses.controller.ts:24-52)

MethodPathPermissionDTO / sourceDescription
POST/houseshouses.createCreateHouseDto (create-house.dto.ts:4-22)Create; 409 dup code (houses.service.ts:19-21); unique index {tenantId, code} (house.schema.ts:23)
GET/houses?page=1&limit=20houses.read-List, paginated meta, no sort (houses.service.ts:25-34; defaults houses.controller.ts:32)
GET/houses/:idhouses.read-Get by ID; 404 House not found. (houses.service.ts:36-40)
PATCH/houses/:idhouses.updateCreateHouseDto (reused - houses.controller.ts:44)Update via $set; 404 (houses.service.ts:42-49); no dup check (index backs it)
DELETE/houses/:idhouses.delete-Soft delete (houses.service.ts:51-54); no member guard; 404

2. Assignment (lives in Students, not Houses)

MethodPathPermissionDTO / sourceDescription
POST/studentsstudent.createCreateStudentDto incl. optional houseId (create-student.dto.ts:39-42)Create student with house
PATCH/students/:idstudent.updateUpdateStudentDto incl. optional houseId (update-student.dto.ts:45-48)Reassign house (student.service.ts:142-155)
  • Transfer does not touch houseId (student.service.ts:185-192).
  • Reference: student.schema.ts:41-42 (houseId → ref: 'House', optional).

3. Request examples

POST /api/v1/houses
{ "name": "Reddy House", "code": "REDDY", "color": "#BA1A1A", "motto": "Brave and Bold" }

POST /api/v1/houses
{ "name": "Nehru House", "code": "NEHRU" }        // color/motto optional

PATCH /api/v1/houses/64f1c2a9e8b1d2c3f4a5b6c7
{ "name": "Reddy House", "code": "REDDY", "color": "#C62828", "motto": "Brave and Bold" }
// note: full CreateHouseDto required by PATCH (houses.controller.ts:44)

POST /api/v1/students
{ "userId": "64f...", "admissionNumber": "ADM2026001", "academicYearId": "64f...",
  "gradeId": "64f...", "sectionId": "64f...", "classId": "64f...", "houseId": "64f..." }

PATCH /api/v1/students/64f...
{ "houseId": "64f..." }                            // reassign house

4. Response shapes

  • List: { data: HouseDoc[], meta: { page, limit, totalItems, totalPages, hasNext, hasPrevious } } (buildPaginationMeta, pagination-query.dto.ts:41-55).
  • Single/created/updated: { data: HouseDoc } (envelope interceptor, 00-shared/07).
  • Delete: 200/204 envelope, no body (houses.service.ts:51-54).
  • House doc fields: _id, name, code, color?, motto?, tenantId, createdBy?, updatedBy?, isDeleted, deletedAt?, deletedBy?, version, createdAt, updatedAt (house.schema.ts:8-19, base.schema.ts:8-34).

5. Error map

CodeMeaningSource
401unauthenticatedJwtAuthGuard (houses.controller.ts:19)
404house missinghouses.service.ts:38, 47, 53
409duplicate code (create)houses.service.ts:19-21
409duplicate code (update, via unique index)house.schema.ts:23 - not service-checked (08 §3)
400DTO validation (class-validator)create-house.dto.ts
500any Mongo error not mappede.g. E11000 race on create (14 §2.4)

6. House document (schema truth)

FieldTypeRequiredNotes
nameString✅trim (house.schema.ts:9-10)
codeString✅trim; unique per tenant (house.schema.ts:12-13, 23)
colorString❌free string (house.schema.ts:15-16)
mottoString❌(house.schema.ts:18-19)

7. Planned / not yet in source

Path / contractStatusSource
GET /students?houseId= filter or GET /houses/:id/members(planned)student.service.ts:106 filters {}; no endpoint exists
Delete guard / cascade on DELETE /houses/:id(planned)houses.service.ts:51-54 no check; student.schema.ts:41-42
sort/q on GET /houses(planned)params exist (pagination-query.dto.ts:21-29), unused (houses.service.ts:30)
Mascot / house master / points fields(planned)absent from house.schema.ts:9-19
House domain events(planned)houses service emits none
Bulk house import(planned)IMPLEMENTATION_PLAN.md:172 (bulk import framework)
QR member check-in, push results(forward-looking)no contract in source

8. Analytics contract (proposed)

houses.list.*, houses.detail.*, houses.editor.* events per 00-shared/10 §8 - not implemented on any client or server (SDK open).