01 — Product Overview (Parents Module)

• 1. Purpose
• 2. Business goals
• 3. User goals
• 4. Stakeholders
• 5. Why this exists
• 6. Dependencies
• 7. Success metrics (proposed)
• 8. Edge cases
• 9. Assumptions (module)
• 10. Open questions (module-level; global ledger in 00-shared/12)
• 11. Glossary (this module)

StudyLyon — multi-tenant ERP / School Management API. This package designs the Parents module client (guardian profiles, student–parent linking, multi-child support) against the implemented NestJS backend. All endpoints, DTO fields, schemas, events, and wire contracts are derived directly from src/modules/parents/**, src/modules/students/**, src/modules/users/**, src/modules/rbac/**, src/infrastructure/**, studylyon-blueprint/04-Modules/Parents.md, and studylyon-blueprint/03-Database/COLLECTIONS.md. No feature is invented; gaps are flagged (planned) / (forward-looking) / (proposed) and itemized in the Assumptions & Open Questions section.

1. Purpose

The Parents module manages guardian identity (occupation, company, income, emergency-contact priority, pickup authorization) and the many-to-many graph between guardians and students (student_parent_links). The blueprint defines the module as "Guardians and emergency contacts" (04-Modules/Parents.md:3) with four responsibilities: guardian profile, student–parent linking, relationship type, and emergency-contact/pickup/financial flags (04-Modules/Parents.md:11-17).

Identity split (critical architectural rule): parents stores guardian business data only. Name, email, phone, avatar live on users (COLLECTIONS.md §2.3 "Domain collections store domain data"; users/schemas/user.schema.ts:16-78). The client must always resolve a parent's display identity through the linked User (parent.schema.ts:9-10).

2. Business goals

3. User goals

• Org admin / admission staff: create a guardian profile from an existing user, link the guardian to one or more students, mark the primary guardian, switch primary when custody changes, unlink a guardian cleanly.
• Parent / guardian: log in and see only their linked children (privacy boundary — persona: "Access: Only linked children", USER_PERSONAS.md:48-53), identify their own relationship per child (mother/father/…), see who is the primary guardian, update their own emergency-contact/pickup flags.
• Multiple-guardian households: mother + father + grandparent each have their own login; each sees the same children; primary flag is per child.
• Admission staff: during enrollment, attach guardians to the newly created student record (POST /students → then link).

4. Stakeholders

Institution admins, admission/front-desk staff, teachers (view linked guardians), parents/guardians (self-service, forward-looking), accountants (financial-responsibility flag feeds billing — fees module), platform support (audit trail via ParentUpdated / ParentDeleted audit events, event-queue-map.ts:38-39), QA + design + engineering.

5. Why this exists

Guardians are the school's primary external stakeholder: they receive attendance, results, and fee communications (blueprint: "Notifications — absentee/result alerts to linked parents", 04-Modules/Parents.md:49). Correctness of the link graph and the primary-guardian flag determines who gets billed, who gets pickups, and who gets called in an emergency — three flows where a wrong link is a real-world incident.

6. Dependencies

7. Success metrics (proposed)

• Zero cross-tenant parent reads (repository scoping structural, base.repository.ts:20-30).
• Link graph integrity: every link's studentId/parentId resolves to a non-deleted doc in the same tenant (today not enforced — see OQ-3).
• Parent self-service adoption: % of parents who log in (requires (forward-looking) my-children endpoints — see OQ-1).
• Duplicate-link incidents = 0 (today not prevented — OQ-2).
• Emergency-contact list accuracy: % of children with ≥ 1 primary guardian (not enforced).

8. Edge cases

• Duplicate profile: second POST /parents with the same userId → 409 DUPLICATE_RESOURCE "Parent profile already exists for this user." (parent.service.ts:30-34, enforced by unique index parent.schema.ts:36).
• Parent not found: GET/PATCH/DELETE /parents/:id and GET /parents/:id/students → 404 RESOURCE_NOT_FOUND "Parent not found." (parent.service.ts:51,77,91,70).
• Link to missing student: POST /parents/link/:studentId calls studentRepo.findById(studentId) but discards the result — a link to a non-existent student is silently created (OQ-3; student-parent-link.service.ts:27).
• Duplicate link: same (studentId, parentId) twice → two link docs allowed (index non-unique, student-parent-link.schema.ts:46) (OQ-2).
• Multiple primary guardians: no server rule prevents two links with isPrimaryGuardian:true for one student (OQ-5).
• Unlink: DELETE /parents/link/:linkId soft-deletes the link; if it was the only link, no parent deletion happens and no re-promotion of another guardian occurs (OQ-4).
• Delete parent with active links: parent soft-deleted, links remain orphaned (pointing at a soft-deleted parent) — no cascade (OQ-3).
• Invalid relationship string: LinkParentDto.relationship is @IsString() with no enum validation (link-parent.dto.ts:19-20); schema enum rejects on save → Mongoose ValidationError → 500 INTERNAL_SERVER_ERROR instead of 400 (OQ-6).
• Invalid ObjectId in :id: CastError → 400 VALIDATION_ERROR "Invalid resource identifier." (http-exception.filter.ts:48,92).
• Parent list ignores q and sort: find() applies only skip/limit (parent.service.ts:58-61) — search UI must not rely on q (OQ-7).

9. Assumptions (module)

• Mobile client is forward-looking: backend is complete; this package is the UI-side spec (same policy as the auth package — PRD Phase 1 excludes native apps, 00-shared/12 A1).
• RBAC is not wired to these endpoints. Global RbacGuard runs (app.module.ts:131), but ParentController declares only @UseGuards(JwtAuthGuard) (parent.controller.ts:23) and no @Permissions(...); the parent.* permissions in the blueprint (04-Modules/Parents.md:64-70) do not exist in ALL_PERMISSIONS (permissions.constants.ts:1-97). Any authenticated user can create/read/update/delete any parent in their tenant. UI must be built with intended-role gating and harden when RBAC lands (OQ-8).
• There is no "my parent profile" resolution. No GET /parents/me and no userId filter on GET /parents; a logged-in parent cannot resolve their own parent profile or children with today's API. The my-children surface is (forward-looking) and needs either a new endpoint or a client-side mapping (OQ-1). Parent role carries only student.read (role.schema.ts:55).
• Parent user accounts are created by admins via POST /users (no invite/password bootstrap specific to parents; no auth_accounts creation from the users module) (OQ-9). ParentCreated fires only after POST /parents (parent.service.ts:38-45).
• No email on parent creation: ParentCreated routes to the in-app queue (event-queue-map.ts:37); email.worker.ts handles only UserRegistered and PasswordResetRequested (email.worker.ts:25-42).
• Blueprint link routes (POST /students/:id/parents, DELETE /students/:id/parents/:linkId, 04-Modules/Parents.md:29-30) differ from the implemented controller routes (/parents/link/..., parent.controller.ts:47-60). Implementation wins; blueprint is historical.

10. Open questions (module-level; global ledger in 00-shared/12)

11. Glossary (this module)