Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ihfaz297/MND/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The MND backend uses three JSON data files to define the transportation network:
  • nodes.json - Locations, stops, and intersections
  • edges.json - Connections between nodes (walking, bus, local transport)
  • routes.json - Bus schedules and trip definitions
All files are located in MND-backend/src/data/.

​
nodes.json

Defines all locations in the system.

​
Structure

[
  {
    "id": "TILAGOR",
    "name": "Tilagor",
    "type": "stop",
    "gmaps_address": "Tilagor, Sylhet, Bangladesh"
  },
  {
    "id": "CAMPUS",
    "name": "Campus",
    "type": "stop",
    "gmaps_address": "Shahjalal University of Science and Technology, Sylhet, Bangladesh"
  },
  {
    "id": "SHAHI_EIDGAH",
    "name": "Shahi Eidgah",
    "type": "intersection",
    "gmaps_address": "Shahi Eidgah, Sylhet, Bangladesh"
  },
  {
    "id": "MEDICAL",
    "name": "Medical",
    "type": "destination",
    "gmaps_address": "Sylhet MAG Osmani Medical College Hospital, Sylhet, Bangladesh"
  }
]

​
Node Fields

​
id
string
required
Unique identifier for the node. Use uppercase with underscores.Examples: TILAGOR, SHAHI_EIDGAH, CAMPUS
​
name
string
required
Human-readable display name.Examples: "Tilagor", "Shahi Eidgah", "Campus"
​
type
string
required
Node classification.Valid types:
  • stop - Bus stop where passengers can board
  • intersection - Connection point between routes
  • destination - Final destination or landmark
​
gmaps_address
string
required
Google Maps address for Distance Matrix API.Best practices:
  • Use specific landmarks when possible
  • Include city and country for accuracy
  • Test addresses in Google Maps first
Examples:
"Tilagor, Sylhet, Bangladesh"
"Shahjalal University of Science and Technology, Sylhet, Bangladesh"
"Medical College Hospital, Sylhet"

​
Adding a New Location

  1. Open MND-backend/src/data/nodes.json
  2. Add a new entry:
{
  "id": "NEW_LOCATION",
  "name": "New Location",
  "type": "stop",
  "gmaps_address": "New Location, Sylhet, Bangladesh"
}
  1. Verify the address in Google Maps
  2. Add edges connecting this node (see next section)

​
edges.json

Defines connections between nodes.

​
Structure

[
  {
    "from": "TILAGOR",
    "to": "SHIBGONJ",
    "mode": "bus",
    "route_ids": ["bus1", "bus2"],
    "time_min": 6,
    "distance_meters": 2046,
    "cost": 0,
    "one_way": false,
    "source": "distance_matrix"
  },
  {
    "from": "CAMPUS",
    "to": "MODINA_MARKET",
    "mode": "walk",
    "time_min": 5,
    "distance_meters": 400,
    "cost": 0,
    "one_way": false,
    "source": "estimated"
  },
  {
    "from": "SHAHI_EIDGAH",
    "to": "SUBIDBAZAR",
    "mode": "local",
    "time_min": 8,
    "distance_meters": 2000,
    "cost": 30,
    "one_way": false,
    "source": "estimated"
  }
]

​
Edge Fields

​
from
string
required
Origin node ID (must exist in nodes.json).
​
to
string
required
Destination node ID (must exist in nodes.json).
​
mode
string
required
Transportation mode.Valid modes:
  • bus - University bus service
  • walk - Walking connection
  • local - Local transportation (rickshaw, CNG)
​
route_ids
array
List of bus route IDs that serve this edge. Required for mode: "bus".Example:
"route_ids": ["bus1", "bus2", "bus3"]
​
time_min
number
required
Travel time in minutes.Note: Use realistic estimates. Walking speed: ~5 km/h, driving: ~20-30 km/h in city.
​
distance_meters
number
required
Distance in meters.
​
cost
number
required
Cost in local currency (0 for bus and walking).Example costs:
  • Bus: 0 (free for students)
  • Walking: 0
  • Local transport: 20-50 BDT
​
one_way
boolean
default:"false"
Whether the edge is one-way only.If false, the graph automatically creates a reverse edge.
​
source
string
Data source for verification.Valid values:
  • distance_matrix - From Google Distance Matrix API
  • estimated - Manual estimation
  • measured - GPS measurement
  • densified_local - Auto-generated local transport
  • densified_walk - Auto-generated walking

​
Adding a New Connection

  1. Open MND-backend/src/data/edges.json
  2. Add a new edge:
{
  "from": "NEW_LOCATION",
  "to": "EXISTING_LOCATION",
  "mode": "bus",
  "route_ids": ["bus1"],
  "time_min": 10,
  "distance_meters": 3000,
  "cost": 0,
  "one_way": false,
  "source": "estimated"
}
  1. If bidirectional, set one_way: false
  2. Add route_ids if served by bus routes

​
Auto-Populating Edges with Distance Matrix API

Use the script to get accurate data from Google: 
cd MND-backend
npm run populate-edges
This script:
  1. Reads nodes from nodes.json
  2. Calls Google Distance Matrix API
  3. Updates edges.json with real distances and times
  4. Respects the 700/month API quota limit
The populate-edges script uses Google Distance Matrix API quota. Monitor usage carefully.

​
routes.json

Defines bus routes and schedules.

​
Structure

[
  {
    "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_1310",
        "direction": "from_campus",
        "stops": [
          "CAMPUS",
          "SUBIDBAZAR",
          "AMBARKHANA",
          "SHAHI_EIDGAH",
          "KUMARPARA",
          "NAIORPUL",
          "SHIBGONJ",
          "TILAGOR"
        ],
        "departure_time": "13:10"
      }
    ]
  }
]

​
Route Fields

​
route_id
string
required
Unique route identifier. Must match IDs in edges.json.Examples: "bus1", "bus2", "bus3"
​
name
string
required
Display name for the route.Examples: "Bus 1", "Express Route", "Campus Shuttle"
​
trips
array
required
List of scheduled trips for this route.

​
Trip Fields

​
trip_id
string
required
Unique trip identifier.Convention: {route_id}_{departure_time}Examples: "bus1_0825", "bus2_1310"
​
direction
string
required
Trip direction.Valid values:
  • to_campus - Inbound to campus
  • from_campus - Outbound from campus
​
stops
array
required
Ordered list of stop IDs the bus visits.Example:
"stops": [
  "TILAGOR",
  "SHIBGONJ",
  "NAIORPUL",
  "CAMPUS"
]
Stops must exist in nodes.json and have corresponding edges in edges.json.
​
departure_time
string
required
Departure time from first stop in HH:MM format (24-hour).Examples: "08:25", "13:10", "17:30"

​
Adding a New Bus Route

  1. Open MND-backend/src/data/routes.json
  2. Add a new route:
{
  "route_id": "bus8",
  "name": "Bus 8",
  "trips": [
    {
      "trip_id": "bus8_0900",
      "direction": "to_campus",
      "stops": [
        "START_LOCATION",
        "INTERMEDIATE_STOP",
        "CAMPUS"
      ],
      "departure_time": "09:00"
    },
    {
      "trip_id": "bus8_1600",
      "direction": "from_campus",
      "stops": [
        "CAMPUS",
        "INTERMEDIATE_STOP",
        "START_LOCATION"
      ],
      "departure_time": "16:00"
    }
  ]
}
  1. Update edges.json to include "bus8" in relevant route_ids
  2. Restart the backend server

​
Updating Bus Schedules

To change departure times:
  1. Find the trip in routes.json
  2. Update the departure_time field
  3. Update the trip_id if needed (convention: {route}_{time})
  4. Restart the server
Example: 
// Before
{
  "trip_id": "bus1_0825",
  "departure_time": "08:25"
}

// After
{
  "trip_id": "bus1_0830",
  "departure_time": "08:30"
}

​
Validation

​
Check Data Integrity

The backend validates data on startup: 
cd MND-backend
npm run dev
Look for errors like:
  • Invalid node ID in edge: X -> Y
  • Route references unknown node: Z
  • Trip has no stops

​
Debug Scripts

Test the graph structure: 
# Debug graph loading
npx tsx src/scripts/debug-graph.ts

# Debug a specific route
npx tsx src/scripts/debug-route.ts TILAGOR CAMPUS

​
Best Practices

​
Node IDs

  • Use uppercase with underscores
  • Keep IDs short but descriptive
  • Don’t change IDs after deployment (breaks user favorites)

​
Google Maps Addresses

  • Test in Google Maps first
  • Use landmarks for better accuracy
  • Include city/country to avoid ambiguity

​
Edges

  • Add bidirectional edges unless truly one-way
  • Use realistic travel times (factor in traffic)
  • Set cost: 0 for free transportation
  • Update source field for tracking

​
Routes

  • Use consistent naming (Bus 1, Bus 2, etc.)
  • List stops in actual visit order
  • Use 24-hour time format
  • Add return trips for all routes

​
Testing Changes

  1. Edit JSON files
  2. Restart backend server
  3. Test API: GET /api/routes?from=X&to=Y&time=08:30
  4. Verify in frontend/mobile app

​
Common Scenarios

​
Scenario 1: Add a New Stop to Existing Route

  1. Add node to nodes.json
  2. Add edges connecting it to adjacent stops
  3. Update route’s stops array in routes.json
  4. Restart server

​
Scenario 2: Change Bus Schedule Times

  1. Edit departure_time in routes.json
  2. Update trip_id to match new time
  3. Restart server

​
Scenario 3: Add a New Bus Route

  1. Create edges in edges.json with new route_id
  2. Add route definition in routes.json
  3. Restart server

​
Scenario 4: Remove a Location

  1. Remove from nodes.json
  2. Remove all edges referencing it from edges.json
  3. Remove from route stops in routes.json
  4. Restart server

​
Example Data Files

See the current production data:

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us