Bus Tracking

Overview

Manages bus fleet, routes, stops, trip scheduling, and real-time GPS tracking via Socket.IO.

Data Model

Bus 1───M BusRoute 1───M BusStop M───M TripStop
│                  │
│                  └───M Trip
│
└──M TripStudentMark (boarding status per student per trip)

Entities

Bus

{
  id: string;
  busNumber: string;       // e.g. "KA-01-AB-1234"
  capacity: number;
  driverId: string;        // EmployeeUser ID
  model: string;           // e.g. "Mahindra Bolero"
  status: 'ACTIVE' | 'MAINTENANCE' | 'RETIRED';
}

BusStop

{
  id: string;
  name: string;
  latitude: number;
  longitude: number;
  address: string;
  sequenceOrder: number;   // stop order on route
}

BusRoute

{
  id: string;
  name: string;            // e.g. "Route A - Whitefield"
  busId: string;
  stops: BusStop[];        // ordered
  estimatedTime: number;   // minutes
}

Trip

{
  id: string;
  busRouteId: string;
  date: Date;
  type: 'PICKUP' | 'DROPOFF' | 'BOTH';
  startTime: string;       // "07:30"
  status: 'SCHEDULED' | 'STARTED' | 'PAUSED' | 'ENDED';
  startOdometer?: number;
  endOdometer?: number;
}

Trip Student Mark

Records each student's boarding status at each stop:

{
  id: string;
  tripId: string;
  studentId: string;
  stopId: string;
  status: 'boaded' | 'alighted' | 'absent' | 'no_show';
  markedAt: Date;
  markedBy: string;        // Driver userId
}

Status	Meaning
boaded	Student got ON the bus
alighted	Student got OFF the bus
absent	Student is absent (not at stop)
no_show	Student was expected but didn't appear

API Endpoints

Bus Management (School Admin)

POST /school-admin/transport/bus/create
GET  /school-admin/transport/bus/list
PUT  /school-admin/transport/bus/:id

POST /school-admin/transport/route/create
GET  /school-admin/transport/route/:id

POST /school-admin/transport/trip/schedule
GET  /school-admin/transport/trip/list?date=2024-04-01

Driver App

POST /driver/bus-tracking/trips/:tripId/start
POST /driver/bus-tracking/trips/:tripId/pause
POST /driver/bus-tracking/trips/:tripId/resume
POST /driver/bus-tracking/trips/:tripId/end

POST /driver/bus-tracking/trips/:tripId/students/mark
{
  "data": {
    "studentId": "uuid",
    "stopId": "uuid",
    "status": "boaded"
  }
}

POST /driver/bus-tracking/incidents
{
  "data": {
    "description": "Engine warning light on",
    "latitude": 12.9716,
    "longitude": 77.5946
  }
}

GET  /driver/bus-tracking/incidents

Live Location

GET /bus-tracking/bus/:busId/live

Returns current trip status and last known GPS coordinates.

Socket.IO Events

Driver → Server

// Driver app connects
const socket = io('https://dev-api.metaonus.in/bus-tracking', {
  auth: { token: driverAccessToken }
});

// Join bus room
socket.emit('join-bus-room', {
  schoolId: 'uuid',
  busId: 'uuid',
  tripId: 'uuid'
});

// Broadcast location (every 5 seconds)
socket.emit('update-location', {
  lat: 12.9716,
  lng: 77.5946,
  speed: 35,        // km/h
  heading: 90,      // degrees
  timestamp: Date.now()
});

// Leave on trip end
socket.emit('leave-bus-room');

Server → Parents App (via Redis adapter)

Parents app subscribes to the same bus room and receives location updates in real-time.

School Admin Live Map

School admin UI shows all active buses on an OpenStreetMap map:

// WebSocket subscription (school-admin-ui)
socket.emit('join-school-room', { schoolId });
socket.on('bus-location-update', ({ busId, lat, lng, speed }) => {
  // Update map marker position
});