Exact wire contracts for the Transport module. Base path /api/v1 (URI
versioning, main.ts); all endpoints JWT-guarded
(transport.controller.ts:23-26), tenant-scoped (base.repository.ts:20-30).
Envelopes per 00-shared/07 §2-3. Permissions from
permissions.constants.ts:62-74 (guards on endpoints not yet wired -
AGENTS.md).
Method Path Permission DTO / source Description
POST /transport/vehiclestransport.vehicle.createCreateVehicleDto (create-vehicle.dto.ts:5-42)Add a vehicle; 409 dup plate (transport.service.ts:38-45); emits VehicleCreated (:47-57) GET /transport/vehicles?page=1&limit=20transport.vehicle.read- List, sort plateNumber asc, paginated meta (transport.service.ts:61-76; transport.controller.ts:36-40) GET /transport/vehicles/:idtransport.vehicle.read- Get by ID; 404 (transport.service.ts:78-82) PATCH /transport/vehicles/:idtransport.vehicle.updateUpdateVehicleDto (PartialType, update-vehicle.dto.ts:4)Update; 404 (transport.service.ts:84-91) DELETE /transport/vehicles/:idtransport.vehicle.delete- Soft delete; 409 if on a route (transport.service.ts:93-110); emits VehicleDeleted
Method Path Permission DTO / source Description
POST /transport/routestransport.route.createCreateRouteDto (create-route.dto.ts:21-60)Create; 409 dup name (transport.service.ts:112-130); emits RouteCreated GET /transport/routes?page=1&limit=20transport.route.read- List, sort name asc (transport.service.ts:132-147) GET /transport/routes/:idtransport.route.read- 404 (transport.service.ts:149-153) PATCH /transport/routes/:idtransport.route.updateUpdateRouteDto (PartialType)Update incl. stops/vehicleId/driverId; ObjectId conversion (transport.service.ts:155-165) DELETE /transport/routes/:idtransport.route.delete- Soft delete; 409 if active assignments (transport.service.ts:167-174)
Method Path Permission DTO / source Description
POST /transport/driverstransport.driver.createCreateDriverDto (create-driver.dto.ts:4-50)Add; 409 dup license OR phone (transport.service.ts:176-199) GET /transport/drivers?page=1&limit=20transport.driver.read- List, sort firstName asc (transport.service.ts:201-216) GET /transport/drivers/:idtransport.driver.read- 404 (transport.service.ts:218-222) PATCH /transport/drivers/:idtransport.driver.updateUpdateDriverDto (PartialType)Update; date re-parse (transport.service.ts:224-238) DELETE /transport/drivers/:idtransport.driver.delete- Soft delete; 409 if on a route (transport.service.ts:240-249)
Method Path Permission DTO / source Description
POST /transport/assigntransport.assignAssignRouteDto (assign-route.dto.ts:4-26)Assign student to route; 409 dup (route, student) (transport.service.ts:251-280); emits StudentRouteAssigned GET /transport/assignments/:studentIdtransport.assign (or route.read context)- Student's assignments, route populated (transport.service.ts:282-286, route-assignment.repository.ts:20-24) DELETE /transport/assignments/:idtransport.assign- Remove assignment (soft delete); 404 (transport.service.ts:288-291)
POST /api/v1/transport/vehicles
{ "plateNumber": "ABC-123", "model": "Toyota Coaster", "capacity": 30,
"type": "bus", "year": 2022, "color": "white" }
POST /api/v1/transport/routes
{ "name": "Route A", "startPoint": "Main Gate", "endPoint": "City Center",
"stops": [ { "name": "Market", "order": 1 }, { "name": "Station", "order": 2 } ],
"vehicleId": "64f...", "driverId": "64f...", "estimatedDuration": 45 }
POST /api/v1/transport/assign
{ "routeId": "64f...", "studentId": "64f...", "shift": "both",
"stopName": "Market", "notes": "Gate 2 pickup" }
List: { data: VehicleDoc[], meta: { page, limit, totalItems, totalPages, hasNext, hasPrevious } } (buildPaginationMeta, transport.service.ts:75).
Single/created/updated: { data: <Doc> } (envelope interceptor, 00-shared/07).
Student assignments: { data: RouteAssignment[] } with routeId populated
(route-assignment.repository.ts:20-24).
Delete: 200/204 envelope, no body.
Code Meaning Source
401 unauthenticated JwtAuthGuard (transport.controller.ts:25)404 entity missing transport.service.ts:80, 101, 151, 173, 220, 237, 248, 290409 dup plate / route name / license / phone / assignment transport.service.ts:42-44, 115, 181-183, 187-189, 257409 dependency blocks delete transport.service.ts:98, 170, 245400 DTO validation (class-validator) create-*.dto.ts
Path Status Source
Live tracking, bus attendance, fee calc, emergency endpoints (planned)IMPLEMENTATION_PLAN.md:229Assignment status PATCH (active/inactive) (planned) - schema field exists, no endpoint (route-assignment.schema.ts:23-28)gap Search/filter query params (q, status, type) (planned) - lists filter {} (transport.service.ts:69, 141, 210)gap Parent bus-tracking read (forward-looking)docs/user-flows/END_TO_END_USER_FLOWS.md:392-406Notifications (e.g. transport.delay) (planned)docs/user-flows/END_TO_END_USER_FLOWS.md:430