Chapter 10

Transport

school_adminnon_teaching_staffparent

Overview

Transport is an optional module (switched on per school via Feature Toggles, Ch. 1.3) covering the full lifecycle of school bus operations: routes and stops, a fleet of vehicles with three different ways to track their live position, student/staff assignments with automatic capacity waitlisting, daily driver trip logs, breakdown/SOS incidents with substitute-vehicle coverage, parent-submitted change requests and "not travelling today" notices, and a compliance dashboard that red-flags vehicles missing a mandatory document. This chapter follows Golden Jubilee's own small fleet: Bus 1 (driver-phone GPS, fully compliant), Bus 2 (a dedicated GPS device, deliberately under-capacity so its route waitlists two students), Bus 3 (no GPS, an outsourced vendor vehicle, running with an expired fitness certificate), and Bus 4 (a spare, substituting for Bus 3 after a breakdown).

Prerequisites

The Transport module must be switched on in Feature Toggles (Ch. 1.3). Branches (Ch. 1.2), classes/sections, and at least one admitted student (Ch. 3) must already exist before students can be assigned to a route.

10.1 Routes & Stops

A Route is a named path (e.g. "Route 1 - Vijayanagar") with a direction (morning, evening, or both) and a fee basis — per-stop (each stop has its own monthly fee) or per-route (one flat fee for the whole route). Each route has an ordered list of Stops, each with its own pickup/drop time, landmark, monthly fee, and optional GPS coordinates (used to render the route on a map and to trigger "bus near your stop" alerts once GPS tracking is live). A branch-scoped admin only ever sees routes for their own branch; an unrestricted admin sees every branch's routes and picks one explicitly when creating a new route.

The Transport Hub landing page with links to every Transport sub-page
Figure 10.125. The Transport Hub — the entry point into every Transport sub-page.
The Route Manager listing all of Golden Jubilee’s routes
Figure 10.126. Route Manager — Golden Jubilee runs three routes: two from Main Branch, one from North Campus.
Route 1’s detail page showing its three stops with pickup/drop times and fees
Figure 10.127. Route 1 - Vijayanagar’s stops, each with its own pickup/drop time and monthly fee (per-stop fee basis).
Route 3’s detail page, a North Campus route with two stops
Figure 10.128. Route 3 - North Campus Feeder — the same stop-management screen, scoped to the North Campus branch.
Field reference
FieldRequiredDescriptionExample
Route Name / Code Required Display name and a short unique code (e.g. GJ-R1) used throughout Trip Log, Incidents, and the Cost Report. Route 1 - Vijayanagar / GJ-R1
Direction Required Morning, evening, or both. Both
Fee Basis Required Per-stop (each stop sets its own fee) or per-route (one flat fee for the whole route). Per-stop
Branch Optional Which branch this route serves. Defaults to the actor’s own branch, or Main Branch for an unrestricted admin. —
Stop Name / Order / Pickup & Drop Time / Fee / Lat-Lng Required Each stop is added individually, in the order the bus visits it. Latitude/longitude are optional but required for the stop to appear on any of the Transport maps. —

10.2 Vehicles & the Three GPS Tracking Sources

A Vehicle record holds its registration number, type, capacity, driver/attendant (either free-text names or, if they have a portal login, linked accounts), an optional assigned route, and whether it is owned or outsourced (outsourced vehicles get a Vendor Contract tab instead of a Fuel Log, since the school doesn't pay for their fuel directly). Independently of ownership, each vehicle picks one of three GPS Tracking Sources:

How does this vehicle report its live position?

Set per-vehicle on the Vehicle Manager edit form — independent of owned/outsourced.

Access granted
gps_tracking_source = driver_phone

The driver's own phone reports location via the browser — see 10.3 for the consent flow this requires.

Access granted
gps_tracking_source = dedicated_device

A physical GPS unit pushes its position directly via an API key — no driver phone or app involved. See 10.3 for pairing.

Access denied
gps_tracking_source = none

No live position at all — Live Tracking and the parent’s map simply show no pin for this vehicle.

The Vehicle Manager listing all four of Golden Jubilee’s vehicles
Figure 10.129. Vehicle Manager — Bus 1 (driver_phone), Bus 2 (dedicated_device), Bus 3 (none, outsourced), and spare Bus 4.
Bus 1’s detail page showing driver Ravi Kumar and attendant Lakshmi Devi
Figure 10.130. Bus 1 (KA-01-AA-1111) — driver-phone GPS, driver and attendant linked to real portal logins.
Field reference
FieldRequiredDescriptionExample
Vehicle No. / Type / Capacity Required Registration number, bus/van/auto, and total seats — capacity is enforced by the Waitlist (10.4). KA-01-AA-1111 / Bus / 40
Driver / Attendant Optional Free-text name, or a linked portal login (grants the transport self-service portal — 10.3, 10.5). —
Assigned Route Optional Which route this vehicle normally runs — drives the default trip type and the Compliance Dashboard's per-route view. —
Operator Type Required Owned (Fuel Log tab) or Outsourced (Vendor Contract tab instead). Owned
GPS Tracking Source Required none / driver_phone / dedicated_device — see the decision above. driver_phone
GPS Ping Interval (seconds) Optional How often a position update is expected — used to compute the "Not Connected" staleness status. 45

Location tracking is opt-in and scoped tightly on both GPS paths. For a Driver Phone vehicle, the driver must explicitly grant consent before their very first Start Trip — this is a full-page, unskippable gate, not a dismissible banner. Location is only ever collected between Start Trip and Complete Route, never outside a trip, and only parents of students on that specific trip (plus Admin/Transport Staff) can see it. Consent can be revoked at any time from the driver's own GPS Setup guide; Start Trip and all trip logging keep working either way — revoking only makes the live position pin unavailable.

The full-page Location Tracking Consent gate shown to a driver before their first trip
Figure 10.131. The consent gate — shown in place of the entire My Transport Duty page until the driver grants or has already granted consent.
The driver’s GPS Setup tab with Android/iOS instructions, a self-test button, and a Revoke Consent control
Figure 10.132. Once granted, the same screen becomes a self-service "GPS Setup" tab — platform-specific setup steps, a location self-test, and Revoke Consent.

For a Dedicated Device vehicle, there is no personal consent to collect (it's the vehicle's own hardware, not the driver's phone) — instead, an admin pairs the device from the Vehicle Manager's GPS Tracking tab, generating a device API key that is shown exactly once, for configuring onto the physical unit. Regenerating the key (e.g. after replacing the hardware) immediately invalidates the old one.

Bus 2’s GPS Tracking tab showing a Paired badge and a Not Connected status
Figure 10.133. Bus 2's GPS Tracking tab — already paired to a dedicated device; connection status and last-ping time shown live.
The one-time device API key reveal after clicking Regenerate Key, with a Copy button
Figure 10.134. Regenerate Key — the new plaintext key is shown once, with a Copy button, then never shown again.
Shown once, on purpose

Neither the pairing key nor a regenerated key can ever be retrieved again after leaving this screen — if it's lost before being configured onto the physical device, the only recovery path is to regenerate a new one.

10.4 Assignments & the Capacity Waitlist

Students and staff are assigned to a route → stop (→ optional pickup point) from the Assignments page. When a route's assigned vehicle is at capacity, the next student assigned automatically becomes Waitlisted rather than rejected outright — Golden Jubilee's Bus 2 seats only 8, so its Route 2 has 8 active riders and 2 waitlisted. Staff assignment is a separate, independently-gated feature (transport.staff_opt_in_mode: off / lightweight / full) — Golden Jubilee runs it in "full" mode, giving staff riders the same assignment history as students.

The Assignments page’s Students tab, with fields to assign a student to a route, stop, and optional pickup point
Figure 10.135. Assignments — Students tab: assign a student to Route → Stop → optional Pickup Point.
The Route Students tab showing every active rider on Route 2
Figure 10.136. Route Students tab — every active rider on a chosen route, with their admission number and class.
The Waitlist tab showing two students waitlisted on Route 2 with their queue position
Figure 10.137. Waitlist tab — Route 2 is at capacity (Bus 2 seats 8); the next two students assigned sit in queue position 1 and 2 instead of being rejected.
Waitlist offers expire automatically

When a seat frees up (a rider is unassigned), the next waitlisted student is automatically offered the spot; if the offer isn't accepted in time, it expires and rolls to the next student in the queue — this runs as a background job, not a manual admin step.

10.5 Daily Trip Log & Live Tracking

Each day, a driver taps Start Trip and Complete Route from their own "My Transport Duty" portal (or an admin enters/corrects a trip record directly). While a trip is in progress, every GPS ping (from either tracking source) is stored as a breadcrumb — after the trip completes, the full path can be replayed as a line on a map from the trip's own View Map link, and while it's still running, Admin/Parent/Driver all see the same live pin update on their own map view.

The admin Trip Log for today, showing Bus 2 in progress and Bus 1 completed
Figure 10.138. Admin Trip Log, filtered to today — Bus 2's morning trip is in progress; Bus 1's already completed, with a Force Complete escape hatch and a View Map link.
The Live Tracking page showing one card per vehicle, with a live map for the vehicle currently mid-trip
Figure 10.139. Live Tracking — one card per vehicle; a bus with no trip running shows no map at all, one mid-trip shows its live pin.
The driver’s own Trip Log tab, showing today’s completed trip with a View Map link
Figure 10.140. The driver's own "Trip Log" tab — Start Trip / Complete Route controls, and a View Map link once a trip is done.
A completed trip’s route replayed as a blue line of real GPS breadcrumbs on a map
Figure 10.141. Trip Route History — the actual path driven, replayed as a blue line connecting every GPS breadcrumb captured during the trip.

One trip, four visible stages — Start Trip and Complete Route are the only two taps a driver ever makes.

10.6 Incidents, Breakdowns & Substitute Vehicles

A driver reports a Breakdown (minor/major severity, admin can also log one manually) or raises an unconditional, single-tap SOS (always critical severity — the one severity level no admin-entered incident can ever choose). When a vehicle breaks down mid-route, an admin assigns a Substitute Vehicle to cover that route until the original is repaired — Golden Jubilee's spare Bus 4 is currently covering Route 3 after Bus 3's breakdown.

The Incident Log showing an open critical SOS from Bus 2 and an open major breakdown from Bus 3
Figure 10.142. Incident Log — an open SOS (critical, from Bus 2's in-progress trip) and an open breakdown (major, Bus 3 — currently covered by substitute Bus 4).

10.7 Change Requests & Not-Travelling Notices

Parents self-serve two things directly from their own Transport view: a Change Request (opt in, change route/stop, or opt out — routed to the admin for approval) and a same-day Not Travelling notice (updates the driver's roll call immediately, no approval needed). Both share the same underlying feature flag and the same admin review surface.

A parent whose child is not opted into transport, with a Request Transport Change button
Figure 10.143. A parent whose child isn't using transport yet — "Not Opted In", with the option to request it.
The Request Transport Change form with Opt In selected and a route dropdown
Figure 10.144. Request Transport Change — the parent picks a request type and a route; submitting sends it to the admin queue below.
The admin Transport Change Requests queue, showing one pending Opt In request with Approve/Reject buttons
Figure 10.145. Transport Change Requests — the admin's queue, with Approve/Reject per request.
The parent’s Not Travelling Today form, with a date and a leg (morning/evening/both) picker
Figure 10.146. Not Travelling Today — a parent reporting their child won't ride the bus, for one or both legs.
The driver’s Today’s Manifest showing one rider marked Not Travelling (Reported) instead of Expected
Figure 10.147. Today's Manifest, from the driver's side — the parent's notice already shows as "Not Travelling (Reported)", ahead of the trip even starting.

10.8 Compliance Dashboard, Vehicle Documents & Route Cost Report

Every vehicle has a Document Register (Insurance, Fitness Certificate, Route Permit, PUC, Road Tax, National Permit, Driver's Licence — some mandatory, some not), a Maintenance Log, and either a Fuel Log (owned vehicles) or a Vendor Contract (outsourced vehicles). The Compliance Dashboard rolls every vehicle's document/maintenance status up into one fleet-wide view, red-flagging any vehicle missing (or overdue on) a mandatory document. The Route Cost Report nets fee revenue against fuel, maintenance, and driver cost, per route, for a chosen date range.

Bus 3’s Document Register showing an expired Fitness Certificate and several missing mandatory documents
Figure 10.148. Bus 3's Document Register — Fitness Certificate has genuinely expired; several other mandatory documents were never uploaded for this outsourced vehicle.
Bus 3’s Vendor Contract tab showing an active contract with Sri Ganesha Travels
Figure 10.149. Vendor Contract tab (outsourced vehicles only) — Bus 3's active contract, in place of a Fuel Log.
The Compliance Dashboard showing four red-flagged vehicles, with Bus 2’s insurance Expiring and Bus 3’s Fitness Certificate Expired
Figure 10.150. Compliance Dashboard — Bus 2's insurance is Expiring soon (within the reminder threshold); Bus 3's Fitness Certificate has Expired; all four vehicles are red-flagged for at least one missing mandatory document.
The Route Cost Report for the current week, showing Route 1’s real fuel cost and a net loss
Figure 10.151. Route Cost Report — Route 1's real logged fuel cost (₹7,035) against zero revenue for this range, for a net loss; the other two routes have no cost entries yet in this window.
Compliance status is always computed against today, not a fixed date

Valid / Expiring / Expired are computed live from each document's validity end date against the real current date (and a configurable reminder threshold, default 30 days) — the same document can silently flip from Valid to Expiring to Expired over time with no admin action at all.

10.9 The Parent Portal

A parent's own Transport view shows their child's route/stop/fee, vehicle, and driver/attendant, plus a live Today's Bus Status card — including a genuinely live map pin whenever that child's bus has a trip actually running.

A parent’s Transport view, showing an Opted In badge, a Not Travelling notice on file, and the child’s route/vehicle/driver details
Figure 10.152. A parent's Transport overview — "Not travelling (notice on file)" reflects the notice submitted in 10.7, immediately, with no admin step in between.
A parent’s Today’s Bus Status card with a live map pin for a bus currently mid-trip
Figure 10.153. Today's Bus Status with a live pin — shown only while the child's leg is pending/boarded and a trip is actually running; a not-travelling or no-trip leg shows no map at all.
One vehicle, one in-progress trip

A vehicle can only ever have one trip in_progress at a time — Start Trip is rejected outright if one is already running. This is also why GPS pings and roll-call taps always land on the correct trip: there's only ever one candidate to write to.

Outsourced vehicles never get a Fuel Log tab

The Fuel Log tab (and therefore the fuel-cost line in the Route Cost Report) only ever appears for an owned vehicle — an outsourced vehicle's running cost is its Vendor Contract's monthly rate instead, since the school doesn't buy its fuel directly.