Bus Schedule Model

Overview

The bus schedule models define the structure of bus routes and their scheduled trips. Each route has multiple trips per day in different directions.

Route Model

interface Route {
  route_id: string;
  name: string;
  trips: Trip[];
}

Source: /home/daytona/workspace/source/MND-backend/src/core/types.ts:31-35

Fields

route_id

string

required

Unique route identifier.Format: bus{number}Examples: bus1, bus2, bus3, bus4, bus5, bus6, bus7

name

string

required

Human-readable route name.Examples: "Bus 1", "Bus 2", "Bus 3"

trips

Trip[]

required

Array of scheduled trips for this route. See Trip model below.

Trip Model

interface Trip {
  trip_id: string;
  direction: 'to_campus' | 'from_campus';
  stops: string[];
  departure_time: string;
}

Source: /home/daytona/workspace/source/MND-backend/src/core/types.ts:24-29

Fields

trip_id

string

required

Unique trip identifier.Format: {route_id}_{departure_time}Examples:

bus1_0825 (Bus 1 departing at 08:25)
bus3_1710 (Bus 3 departing at 17:10)

direction

string

required

Trip direction.

Show Values

to_campus: Heading towards university campus (morning commute)from_campus: Departing from campus (afternoon/evening)

stops

string[]

required

Ordered array of node IDs representing the stop sequence.

First element: Origin stop
Last element: Final destination
Middle elements: Intermediate stops in order

Example: ["TILAGOR", "SHIBGONJ", "NAIORPUL", "KUMARPARA", "CAMPUS"]

departure_time

string

required

Scheduled departure time from the first stop in HH:MM format (24-hour).Examples: "08:25", "13:10", "17:10"

Complete Route Example

Bus 1 Schedule

{
  "route_id": "bus1",
  "name": "Bus 1",
  "trips": [
    {
      "trip_id": "bus1_0825",
      "direction": "to_campus",
      "stops": [
        "TILAGOR",
        "SHIBGONJ",
        "NAIORPUL",
        "KUMARPARA",
        "SHAHI_EIDGAH",
        "AMBARKHANA",
        "SUBIDBAZAR",
        "PATHANTULA",
        "MODINA_MARKET",
        "CAMPUS"
      ],
      "departure_time": "08:25"
    },
    {
      "trip_id": "bus1_0930",
      "direction": "to_campus",
      "stops": [
        "TILAGOR",
        "SHIBGONJ",
        "NAIORPUL",
        "KUMARPARA",
        "CHOWHATTA",
        "AMBARKHANA",
        "SUBIDBAZAR",
        "PATHANTULA",
        "MODINA_MARKET",
        "CAMPUS"
      ],
      "departure_time": "09:30"
    },
    {
      "trip_id": "bus1_1310",
      "direction": "from_campus",
      "stops": [
        "CAMPUS",
        "SUBIDBAZAR",
        "AMBARKHANA",
        "SHAHI_EIDGAH",
        "KUMARPARA",
        "NAIORPUL",
        "SHIBGONJ",
        "TILAGOR"
      ],
      "departure_time": "13:10"
    },
    {
      "trip_id": "bus1_1710",
      "direction": "from_campus",
      "stops": [
        "CAMPUS",
        "SUBIDBAZAR",
        "AMBARKHANA",
        "SHAHI_EIDGAH",
        "KUMARPARA",
        "NAIORPUL",
        "SHIBGONJ",
        "TILAGOR"
      ],
      "departure_time": "17:10"
    }
  ]
}

All 7 Routes Overview

Route Summary

Route ID	Name	Trips	Primary Coverage
bus1	Bus 1	4	Tilagor ↔ Campus (via Shahi Eidgah)
bus2	Bus 2	4	Tilagor ↔ Campus (alternative route)
bus3	Bus 3	5	Naiorpul ↔ Campus (via Jail Rd)
bus4	Bus 4	5	Naiorpul ↔ Campus (alternative)
bus5	Bus 5	4	Lakkatura ↔ Campus
bus6	Bus 6	4	Mixed origins → Campus
bus7	Bus 7	4	Sheikhghat/Shahi Eidgah → Campus

Morning Schedule (to Campus)

30 - Bus 6 (from Naiorpul)
25 - Bus 1 (from Tilagor)
25 - Bus 4 (from Naiorpul)
30 - Bus 2 (from Tilagor)
30 - Bus 3 (from Naiorpul)
30 - Bus 5 (from Lakkatura)
35 - Bus 7 (from Sheikhghat)
25 - Bus 2 (from Tilagor)
25 - Bus 3 (from Naiorpul)
30 - Bus 1 (from Tilagor)
30 - Bus 4 (from Naiorpul)
30 - Bus 5 (from Lakkatura)
35 - Bus 6 (from Shahi Eidgah)
35 - Bus 7 (from Shahi Eidgah)

Afternoon/Evening Schedule (from Campus)

10 - Bus 1, 2, 3, 4, 5 (all depart)
10 - Bus 6, 7
10 - Bus 1, 2, 3, 4, 5, 6, 7 (all depart)
30 - Bus 3, 4 (late evening)

Trip Directions

to_campus

Morning commute routes heading towards the university.

{
  "trip_id": "bus1_0825",
  "direction": "to_campus",
  "stops": ["TILAGOR", "SHIBGONJ", ..., "CAMPUS"],
  "departure_time": "08:25"
}

Characteristics:

First stop: Residential areas (Tilagor, Naiorpul, etc.)
Last stop: Always CAMPUS
Time range: 07:30 - 09:35

from_campus

Afternoon/evening routes departing from university.

{
  "trip_id": "bus1_1710",
  "direction": "from_campus",
  "stops": ["CAMPUS", "SUBIDBAZAR", ..., "TILAGOR"],
  "departure_time": "17:10"
}

Characteristics:

First stop: Always CAMPUS
Last stop: Various destinations (city center, residential areas)
Time range: 13:10 - 18:30

Stop Sequences

Stop order matters and represents the actual route path:

Linear Route

{
  "stops": ["A", "B", "C", "D"]
}

The bus goes: A → B → C → D in that exact order.

Circular Route

Some trips have circular patterns:

{
  "trip_id": "bus1_1310",
  "stops": [
    "CAMPUS",
    "SUBIDBAZAR",
    "AMBARKHANA",
    "SHAHI_EIDGAH",
    "KUMARPARA",
    "NAIORPUL",
    "SHIBGONJ",
    "TILAGOR",
    "SHAHI_EIDGAH",    // Revisits earlier stop
    "AMBARKHANA",       // Revisits earlier stop
    "SUBIDBAZAR",       // Revisits earlier stop
    "PATHANTULA",
    "MODINA_MARKET",
    "CAMPUS"            // Returns to start
  ]
}

Some routes revisit stops to serve both directions in a single trip.

Time Calculations

Arrival Time Estimation

Estimate arrival at each stop assuming 5 minutes per stop:

function estimateArrival(
  trip: Trip, 
  stopId: string
): string | null {
  const stopIndex = trip.stops.indexOf(stopId);
  if (stopIndex === -1) return null;
  
  const departureMinutes = timeToMinutes(
    parseTime(trip.departure_time)
  );
  
  const avgTimePerStop = 5; // minutes
  const arrivalMinutes = 
    departureMinutes + (stopIndex * avgTimePerStop);
  
  return minutesToTime(arrivalMinutes);
}

// Example:
const trip = {
  trip_id: "bus1_0825",
  departure_time: "08:25",
  stops: ["TILAGOR", "SHIBGONJ", "NAIORPUL", "CAMPUS"]
};

estimateArrival(trip, "TILAGOR");   // "08:25" (origin)
estimateArrival(trip, "SHIBGONJ");  // "08:30" (1 stop * 5 min)
estimateArrival(trip, "NAIORPUL");  // "08:35" (2 stops * 5 min)
estimateArrival(trip, "CAMPUS");    // "08:40" (3 stops * 5 min)

Trip Duration

function tripDuration(trip: Trip): number {
  return (trip.stops.length - 1) * 5; // minutes
}

// Example: 10 stops = 9 segments * 5 min = 45 minutes

API Usage

Get All Routes

GET /api/routes/list

Returns summary of all routes:

{
  "count": 7,
  "routes": [
    {
      "route_id": "bus1",
      "name": "Bus 1",
      "trips_count": 4
    }
    // ... more routes
  ]
}

Get Route Schedule

GET /api/buses/schedule/bus1

Returns full schedule:

{
  "route_id": "bus1",
  "name": "Bus 1",
  "trips": [
    {
      "trip_id": "bus1_0825",
      "direction": "to_campus",
      "departure_time": "08:25",
      "stops": [...],
      "stop_count": 10
    }
    // ... more trips
  ]
}

Get Route Details

GET /api/routes/bus1

Returns route with unique stops:

{
  "route_id": "bus1",
  "name": "Bus 1",
  "total_trips": 4,
  "stops": [
    {
      "id": "TILAGOR",
      "name": "Tilagor",
      "type": "stop"
    }
    // ... all unique stops
  ],
  "trips": [...]
}

Validation

Required Fields

function validateTrip(trip: Trip): boolean {
  if (!trip.trip_id || !trip.direction || 
      !trip.departure_time || !trip.stops) {
    return false;
  }
  
  if (trip.stops.length < 2) {
    return false; // Need at least origin and destination
  }
  
  if (!['to_campus', 'from_campus'].includes(trip.direction)) {
    return false;
  }
  
  return true;
}

Direction Validation

function validateDirection(trip: Trip): boolean {
  if (trip.direction === 'to_campus') {
    // Last stop should be CAMPUS
    return trip.stops[trip.stops.length - 1] === 'CAMPUS';
  } else {
    // First stop should be CAMPUS
    return trip.stops[0] === 'CAMPUS';
  }
}

Time Format Validation

function validateTime(time: string): boolean {
  const timeRegex = /^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$/;
  return timeRegex.test(time);
}

validateTime("08:25");  // true
validateTime("17:10");  // true
validateTime("25:00");  // false (invalid hour)
validateTime("08:60");  // false (invalid minute)

RouteLeg

Bus legs reference trip_id

Node

Stops array contains node IDs

Bus API

Endpoints using schedule data

Route Planning

Uses schedules to plan routes

​Overview

​Route Model

​Fields

​Trip Model

​Fields

​Complete Route Example

​Bus 1 Schedule

​All 7 Routes Overview

​Route Summary

​Morning Schedule (to Campus)

​Afternoon/Evening Schedule (from Campus)

​Trip Directions

​to_campus

​from_campus

​Stop Sequences

​Linear Route

​Circular Route

​Time Calculations

​Arrival Time Estimation

​Trip Duration

​API Usage

​Get All Routes

​Get Route Schedule

​Get Route Details

​Validation

​Required Fields

​Direction Validation

​Time Format Validation

​Related Models

RouteLeg

Node

Bus API

Route Planning

Overview

Route Model

Fields

Trip Model

Fields

Complete Route Example

Bus 1 Schedule

All 7 Routes Overview

Route Summary

Morning Schedule (to Campus)

Afternoon/Evening Schedule (from Campus)

Trip Directions

to_campus

from_campus

Stop Sequences

Linear Route

Circular Route

Time Calculations

Arrival Time Estimation

Trip Duration

API Usage

Get All Routes

Get Route Schedule

Get Route Details

Validation

Required Fields

Direction Validation

Time Format Validation

Related Models