04 - Information Architecture (Transport Module)

• 1. Sitemap
• 2. Navigation rules
• 3. Entity model (source-derived)
• 4. Relationship semantics
• 5. IA principles

IA of the Transport module client. Global shells/navigation per 00-shared/05; this file maps module pages and their data dependencies.

1. Sitemap

/transport                      Transport Overview (module hub)
/transport/vehicles             Vehicle list
/transport/vehicles/:id         Vehicle detail
/transport/vehicles/new         Vehicle create form        (sheet on tablet)
/transport/drivers              Driver list
/transport/drivers/:id          Driver detail
/transport/drivers/new          Driver create form         (sheet on tablet)
/transport/routes               Route list
/transport/routes/:id           Route detail
/transport/routes/:id/edit      Route editor w/ stops     (sheet on tablet)
/transport/routes/new           Route create form
/transport/assign               Assign student to route    (sheet)
/transport/students/:studentId/transport  Student route assignments
/transport/live                 Live tracking (planned)
/transport/attendance           Bus attendance (planned)
/transport/fees                 Transport fee calc (planned)

(planned) routes exist only as placeholders per IMPLEMENTATION_PLAN.md:229.

2. Navigation rules

• Overview is the hub: three summary tiles (vehicles, drivers, routes) + "Assign student" entry. Counts come from paginated list calls (transport.controller.ts:36-40, 66-70, 96-100) - meta.totalItems (buildPaginationMeta, transport.service.ts:75, 146, 215).
• List -> detail via row tap; detail -> edit via FAB/action; lists are the only read entry for entities (no global search endpoint exists; 00-shared/05 global search is out of transport scope).
• Route editor and assign flows open as bottom sheets on phone, centered dialogs on tablet/desktop (per 00-shared/03 AppBottomSheet).

3. Entity model (source-derived)

Vehicle (vehicles)                    Driver (drivers)
  tenantId*                             tenantId*
  plateNumber (unique/tenant)           firstName, lastName
  model, capacity (min 1)               licenseNumber (unique/tenant)
  type: bus|van|car                     phone (unique/tenant), email?
  status: active|maintenance|           status: active|inactive|on_leave
          inactive                        licenseExpiry?, address?,
  year?, color?, insuranceExpiry?,        emergencyContact?, joinedAt?, notes?
  notes?
vehicle.schema.ts:7-50               driver.schema.ts:7-51

TransportRoute (transport_routes)     RouteAssignment (route_assignments)
  tenantId*                             tenantId*
  name (unique/tenant)                  routeId -> TransportRoute (required)
  startPoint, endPoint                  studentId -> Student (required)
  stops: [{name, order}]                shift: morning|evening|both (required)
  vehicleId -> Vehicle?                 status: active|inactive
  driverId -> Driver?                   stopName?, assignedAt?, notes?
  status: active|inactive               unique (tenantId, routeId, studentId)
  estimatedDuration?, notes?            index (tenantId, studentId)
route.schema.ts:7-44                route-assignment.schema.ts:7-46

• tenantId, isDeleted, timestamps, version come from BaseSchema and are never read from request bodies (AGENTS.md conventions; base.repository.ts:20-36).

4. Relationship semantics

• Route -> Vehicle: optional single reference (route.schema.ts:26-27); a vehicle can appear on multiple routes (no uniqueness on route.vehicleId) but cannot be deleted while referenced (transport.service.ts:94-99).
• Route -> Driver: same pattern (route.schema.ts:29-30; transport.service.ts:241-246).
• Student -> RouteAssignment: 1..N (a student can be on multiple routes via separate assignments; same pair blocked by unique index route-assignment.schema.ts:42-45).
• Assignment -> route populated on student lookup (route-assignment.repository.ts:20-24).

5. IA principles

• Entity-first IA: vehicle/driver/route lists are pure CRUD surfaces; assignment lives under students (student-centric) and is reachable from the overview.
• Deletion always routes through a confirm + dependency explanation (409 guards, transport.service.ts:94-99, 168-171, 241-246).
• Master-detail on tablet/desktop (00-shared/05 §2).