01 - Product Overview (Transport Module)
StudyLyon - multi-tenant ERP / School Management API. This package designs the Transport module client (Flutter, forward-looking spec) against the implemented NestJS backend. All endpoints, DTO fields, schemas, domain events, permissions and wire contracts are derived directly from
src/modules/transport/**,src/modules/students/**,src/modules/rbac/permissions.constants.ts,docs/IMPLEMENTATION_PLAN.mdanddocs/user-flows/END_TO_END_USER_FLOWS.md. 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.
1. Purpose
Transport manages the school fleet and daily movement of students:
- Vehicles - fleet register (plate, model, capacity, type, status).
- Drivers - licensed staff register (license, phone, contact details).
- Routes - fixed paths with ordered stops, assigned vehicle + driver.
- Assignments - which student rides which route, on which shift, from which stop.
Everything is tenant-scoped (tenantId on every document) and soft-delete capable;
the repository layer injects both scopes into every query
(base.repository.ts:20-30). All endpoints are JWT-guarded
(transport.controller.ts:23-26).
| Responsibility | Source |
|---|---|
| Vehicle CRUD + soft delete | transport.controller.ts:30-58, transport.service.ts:37-110 |
| Route CRUD + soft delete | transport.controller.ts:60-88, transport.service.ts:112-174 |
| Driver CRUD + soft delete | transport.controller.ts:90-118, transport.service.ts:176-249 |
| Student <-> route assignment | transport.controller.ts:120-136, transport.service.ts:251-291 |
| Duplicate guards (plate/license/phone/route name/assignment) | transport.service.ts:38-45, 113-116, 177-190, 252-258 |
| Delete guards (in-use vehicle/driver/route) | transport.service.ts:94-99, 168-171, 241-246 |
| Unique compound indexes | vehicle.schema.ts:50, driver.schema.ts:50-51, route.schema.ts:44, route-assignment.schema.ts:42-46 |
| Tenant scoping + soft-delete on every query | base.repository.ts:20-30 |
| Student transport requirement flag | student.schema.ts:53-54 |
| RBAC permissions | permissions.constants.ts:62-74 |
2. Business goals
| Goal | Measure |
|---|---|
| No duplicate vehicles | unique {tenantId, plateNumber} + service 409 (vehicle.schema.ts:50, transport.service.ts:38-45) |
| No duplicate drivers | unique {tenantId, licenseNumber} and {tenantId, phone} + service 409 (driver.schema.ts:50-51, transport.service.ts:177-190) |
| No duplicate routes | unique {tenantId, name} + service 409 (route.schema.ts:44, transport.service.ts:113-116) |
| One assignment per (student, route) | unique {tenantId, routeId, studentId} + service 409 (route-assignment.schema.ts:42-45, transport.service.ts:252-258) |
| Referential integrity on delete | in-use vehicle/driver/route cannot be deleted (409) (transport.service.ts:94-99, 168-171, 241-246) |
| Cross-tenant isolation | every query tenant-scoped via BaseRepository.scopedFilter (base.repository.ts:20-30) |
| Audit trail | VehicleCreated / VehicleDeleted / RouteCreated / StudentRouteAssigned events (transport.service.ts:47-57, 102-109, 121-128, 267-278) |
3. User goals
- Transport admin / school admin: keep the fleet and driver register accurate; define routes with stops; assign vehicles and drivers; assign students to routes and shifts; view a student's current route assignments.
- Parent: (forward-looking) see the child's route assignment and stop
(
docs/user-flows/END_TO_END_USER_FLOWS.md:392-406). - Student: (forward-looking) know which bus/stop/shift to use.
4. Scope
4.1 In scope (implemented backend)
Vehicle, driver and route CRUD with paginated lists (?page=1&limit=20 defaults,
transport.controller.ts:38, 68, 98); ordered stop arrays on routes; student-route
assignment with shift (morning/evening/both), stop and notes; per-student
assignment lookup with populated route; soft delete with conflict guards.
4.2 Planned (IMPLEMENTATION_PLAN.md:229 - "Live tracking, bus attendance, fee
calc, emergency", 6 days)
Live vehicle tracking, bus attendance, transport fee calculation, emergency
handling. Documented only as roadmap items; no backend exists - marked (planned)
throughout this package.
4.3 Forward-looking (client roadmap)
Parent-facing "bus tracking" read of a child's route (GET /transport/assignments/:studentId,
referenced in docs/user-flows/END_TO_END_USER_FLOWS.md:406), QR-based boarding
(forward-looking), push alerts (e.g. transport.delay notification type,
docs/user-flows/END_TO_END_USER_FLOWS.md:430).
4.4 Proposed (analytics)
Analytics events on screens (transport.*.*) per 00-shared/10 §8 - (proposed).
5. Non-goals (this version)
- Capacity enforcement at assignment time (no check in
assignStudent,transport.service.ts:251-266) - flagged as QA gap,(planned). - Search/filter beyond pagination (list queries filter
{},transport.service.ts:69, 141, 210). - Driver-vehicle pairing as first-class entity (only via route
vehicleId/driverId,route.schema.ts:26-30). - Assignment status change API (status exists on schema
route-assignment.schema.ts:23-28, no endpoint to flip it; only soft delete viaDELETE /assignments/:id).