01 - Product Overview (Houses Module)

• 1. Purpose
• 2. Business goals
• 3. User goals
• 4. Scope
  • 4.1 In scope (implemented backend)
  • 4.2 Planned (not in source; absent from IMPLEMENTATION_PLAN.md)
  • 4.3 Forward-looking (client roadmap)
  • 4.4 Proposed (analytics)
• 5. Non-goals (this version)

StudyLyon - multi-tenant ERP / School Management API. This package designs the Houses module client (Flutter, forward-looking spec) against the implemented NestJS backend. All endpoints, DTO fields, schemas, permissions and wire contracts are derived directly from src/modules/houses/**, src/modules/students/**, src/modules/rbac/permissions.constants.ts, docs/IMPLEMENTATION_PLAN.md and the shared spec in design-docs/00-shared/. No feature is invented - anything not present in source is flagged (planned) / (proposed) / (forward-looking).

Heads-up: per the PRD, the mobile client is out of Phase 1 scope (PRODUCT_REQUIREMENTS_DOCUMENT.md:144, flagged in 00-shared/12 A1); this package is the forward-looking spec the client will be built against later. Houses is one of the smallest modules in the backend - a single controller/service/repository slice.

1. Purpose

Houses manages the school's house system (e.g. Reddy, Nehru, Tagore): named, color-coded groups students are assigned to for sports, cultural and inter-house competition. The module provides:

• House CRUD - name, code, color, motto (no mascot / house master / points yet).
• Student assignment - a student points at a house via houseId; there is no house-side assignment endpoint (see §3.2).
• Tenant-scoped, soft-deletable documents with a unique {tenantId, code} index.

2. Business goals

3. User goals

• School / house admin: create and maintain the house roster (name, code, color, motto); keep the palette unambiguous so inter-house UI stays readable.
• Registrar: assign a house to a student at admission (houseId in create-student.dto.ts:39-42) and reassign later (update-student.dto.ts:45-48).
• Teacher / student / parent: (forward-looking) see which house a student belongs to and per-house member lists - no dedicated read surface exists in source today.

4. Scope

4.1 In scope (implemented backend)

House CRUD: create (POST /houses), paginated list (GET /houses?page=1&limit=20), get by id (GET /houses/:id), update (PATCH /houses/:id), soft delete (DELETE /houses/:id) - houses.controller.ts:24-52. All JWT-guarded, tenant-scoped. Student-side assignment via POST /students / PATCH /students/:id (student.controller.ts:38, 56).

4.2 Planned (not in source; absent from IMPLEMENTATION_PLAN.md)

IMPLEMENTATION_PLAN.md contains no houses entries; the following are product gaps this package flags (planned):

• House member list endpoint / GET /students?houseId= filter (see 09 §G1).
• Delete guard - deleting a house does not check assigned students (houses.service.ts:51-54; student.schema.ts:41-42 dangling ref).
• House mascot, house master (staff lead), points ledger - none in house.schema.ts:9-19.
• Domain events (HouseCreated, StudentHouseAssigned) - houses service emits none (contrast student.service.ts:79-91).

4.3 Forward-looking (client roadmap)

Push notifications on house events (inter-house results) and QR-based member check-in (forward-looking) - no contract exists anywhere in source.

4.4 Proposed (analytics)

Screen analytics events houses.*.* per 00-shared/10 §8 - (proposed).

5. Non-goals (this version)

• House points / inter-house leaderboard (no field or endpoint).
• Bulk import of houses (Phase 3 bulk import, IMPLEMENTATION_PLAN.md:172).
• Membership management inside the houses API - assignment is exclusively a student concern (student.schema.ts:41-42).
• Color uniqueness enforcement - duplicates are legal at the API level (QA item, 14 §2).