Skip to main content

Bus Tracking

A student opens /dashboard/bus and sees the bus they're assigned to: bus number, route, driver, the most recent location update, and an ETA. The admin's Transport module configures the routes, drivers, and vehicles that this student-facing card pulls from. Live location is sourced from the bus / driver device upstream and surfaces as a "last update" timestamp on the card.

At a glance​

Who can do thisStudents view (only) · Admin configures routes, drivers, buses
Where it livesStudent app /dashboard/bus · Admin /dashboard/school/:id/transport/{bus,driver,route}
Live dataBus number, route, driver, last-update timestamp, ETA
Triggers notifications?Intended — bus-delayed / bus-arriving alerts (see edge cases)
Related featuresTransport (admin) · Notifications

How it flows​

Status lifecycle​

A bus assignment doesn't have a multi-state machine the student sees, but the admin's transport records have a basic active/inactive toggle.

Step-by-step​

1. Admin sets up Transport​

  • App / route: Admin → /dashboard/school/:id/transport (defaults to the Bus tab if :tab is not in the URL — see Transport).
  • Three tabs (the URL keeps them in sync with /transport/:tab):
    • Route — create named routes with stops and schedule.
    • Driver — register drivers (name, phone, license).
    • Bus — create a vehicle (bus number / registration), then link it to a route + driver.
  • Each tab is a paginated DataTable with create / view / delete (with confirm modal) actions.

2. Student is assigned to a route​

  • Done via class / student management (not directly on the transport page). Once assigned, the student's /dashboard/bus resolves to a specific bus.

3. Driver / device streams location​

  • Live location is upstream of the apps — it comes from a driver-side data source (driver app or onboard GPS tracker) that pushes coordinates to the backend on a recurring cadence. The student app never receives raw lat/long; it shows derived fields:
    • Last Update: how long ago the most recent ping arrived.
    • ETA: time remaining to the student's stop, computed from current location + route schedule.

4. Student opens the Bus page​

  • App / route: Student app → /dashboard/bus (BusPage + BusCard).
  • The card shows:
    • Bus number (e.g. MH 01 AB 1234).
    • Last Update (e.g. 3m ago) and an ETA chip (e.g. 12 min).
    • A bus image placeholder.
    • Route name + Driver name.
    • Two icon buttons (call + alert / SOS).
  • Today's BusPage renders a single bus card with example values; in production it will resolve the assigned bus per logged-in student.

5. Student takes action​

  • Call — taps the phone icon → device dialler with the driver's number.
  • Alert / SOS — taps the alert icon → raises an issue (e.g. driver no-show, accident, harassment).

Edge cases & things to test​

  • No assignment: student isn't linked to any route — page should show a friendly empty state, not a stub card with mock values.
  • Bus inactive / removed: admin deletes the bus while a student is on the page — next load should show "no bus assigned" rather than a stale BusCard.
  • Stale GPS ping: no driver pings in 30+ minutes — Last Update should clearly read 30m ago (or similar) and the ETA chip should mark itself as stale instead of a confidently-wrong number.
  • No location ever received: brand-new bus, never streamed — page should not show ETA -- as if it were a real number.
  • Driver swap mid-route: admin reassigns a different driver to the bus — student's card should reflect the new driver name without an app restart.
  • Route reassignment: student changes route mid-term — old bus should disappear, new one should resolve.
  • Call button: missing driver phone — call button should be disabled (and not crash the device dialler with tel:undefined).
  • SOS / alert button: tapping it twice in 5s should not double-fire the alert.
  • Multi-bus household / sibling overlap: a student with multiple linked routes (rare, but on bus changes) — should pick the active one, not the deleted one.
  • Time-zone drift: "Last Update" must respect device locale; a student in IST should not see UTC offsets.
  • Network offline: opening /dashboard/bus offline should show a cached snapshot with a clear "stale data" hint.
  • Notifications for delays / arrivals: when wired up, verify a "bus delayed" push lands in Notifications and deep-links to /dashboard/bus.
  • Privacy: only the assigned student should see their bus; switching accounts should not leak the previous student's bus card.