System Architecture

Overview

MND (My Next Destination) is a multi-platform university transit navigation system built for Shahjalal University of Science and Technology in Sylhet, Bangladesh. The system provides intelligent route planning that combines scheduled free bus services with on-demand local transportation (CNG/rickshaw).

Node.js Backend

Express REST API with TypeScript

Flutter Mobile

Cross-platform iOS/Android app

React Web

Web dashboard for route planning

High-Level Architecture

Backend Architecture (Node.js)

Project Structure

MND-backend/
├── src/
│   ├── api/              # REST API controllers
│   │   ├── authController.ts
│   │   ├── favoritesController.ts
│   │   ├── routesController.ts
│   │   ├── upcomingController.ts
│   │   └── validation.ts
│   ├── core/             # Business logic
│   │   ├── graph.ts      # Graph data structure
│   │   ├── planner.ts    # Route planning algorithms
│   │   ├── types.ts      # TypeScript interfaces
│   │   └── auth.ts       # Magic link authentication
│   ├── data/             # JSON "database"
│   │   ├── nodes.json    # 19 locations
│   │   ├── edges.json    # 289 connections
│   │   ├── routes.json   # 7 bus routes
│   │   ├── users.json    # User accounts
│   │   └── favorites.json # Saved routes
│   ├── infra/            # External services
│   │   └── distanceMatrixClient.ts
│   └── server.ts         # Express app entry point
└── package.json

Core Components

Graph Engine (graph.ts)

Manages the transportation network as a graph data structure.Key Features:

Loads 19 nodes (locations) from nodes.json
Loads 289 edges (connections) from edges.json
Builds adjacency list for efficient traversal
Implements Dijkstra’s shortest path algorithm
Supports bus, local, and walking modes

Data Structure:

export class Graph {
    private nodes: Map<string, Node> = new Map();
    private edges: Edge[] = [];
    private routes: Map<string, Route> = new Map();
    private adjacencyList: AdjacencyList = {};
}

Route Planner (planner.ts)

Implements 4 routing strategies to find optimal paths.Strategies:

Direct Bus - Single bus from origin to destination
Bus + Local - Bus as far as possible, then CNG/rickshaw
Transfer - Multi-leg journey with bus transfers
Local Only - Fallback when buses are unavailable

Returns:

Fastest route (minimum total time)
Least local route (minimum paid transport)

export class RoutePlanner {
    public async planRoute(
        from: string,
        to: string,
        requestTime: string
    ): Promise<RouteResponse>
}

REST API (server.ts)

Express.js server exposing route planning and user features.Endpoints:

GET /api/routes - Plan a route
GET /api/nodes - Get all locations
GET /api/routes/list - Get bus routes
POST /api/auth/send-link - Magic link login
GET /api/favorites - User’s saved routes
GET /api/buses/upcoming - Next buses from location

Example Response:

{
  "from": "TILAGOR",
  "to": "CAMPUS",
  "requestTime": "08:30",
  "options": [
    {
      "label": "Fastest Route",
      "category": "fastest",
      "type": "direct",
      "transfers": 0,
      "totalTimeMin": 45,
      "totalCost": 0,
      "legs": [...]
    }
  ]
}

Distance Matrix Client

Fallback to Google Maps when graph data is insufficient.Use Cases:

Local transport segments not in graph
Walking distances between nodes
Real-time traffic estimates

Caching Strategy:

Caches API responses for 7 days
Reduces API costs (Google charges per request)
Tracks monthly/daily usage limits

Mobile App Architecture (Flutter)

Project Structure

mnd_flutter/
├── lib/
│   ├── main.dart          # App entry point
│   ├── config/            # Configuration
│   │   ├── api_config.dart
│   │   └── app_theme.dart
│   ├── models/            # Data models
│   │   ├── node.dart
│   │   ├── route_option.dart
│   │   ├── route_leg.dart
│   │   ├── favorite.dart
│   │   └── bus_schedule.dart
│   ├── services/          # API clients
│   │   ├── api_service.dart
│   │   ├── route_service.dart
│   │   ├── auth_service.dart
│   │   ├── favorite_service.dart
│   │   └── bus_service.dart
│   ├── screens/           # UI screens
│   │   ├── home/
│   │   ├── route_map/
│   │   ├── favorites/
│   │   ├── profile/
│   │   └── buses/
│   ├── widgets/           # Reusable components
│   │   └── route_card.dart
│   └── providers/         # State management
│       └── auth_provider.dart
└── pubspec.yaml

State Management

MND uses Provider for state management:

class AuthProvider extends ChangeNotifier {
  User? _user;
  bool _isAuthenticated = false;
  
  Future<void> login(String email) async {
    // Magic link authentication
    await authService.sendMagicLink(email);
    notifyListeners();
  }
}

The Flutter app uses Google Maps Flutter plugin to display routes with turn-by-turn directions.

Web Dashboard Architecture (React)

Key Features

Route Planning

Interactive map with origin/destination selection

Schedule Browser

View all bus schedules and departure times

Admin Panel

Manage routes, buses, and user data

Analytics

Usage statistics and popular routes

Data Flow

Route Planning Request Flow

Authentication Flow (Magic Link)

File-Based Database

Instead of a traditional database, MND uses JSON files for data persistence:

This approach is suitable for MVP/demo purposes but should be replaced with a real database (PostgreSQL, MongoDB) for production use.

JSON Data Files

nodes.json
edges.json
routes.json
users.json
favorites.json

Stores all 19 locations in the network:

[
  {
    "id": "TILAGOR",
    "name": "Tilagor",
    "type": "stop",
    "gmaps_address": "Tilagor, Sylhet, Bangladesh"
  },
  {
    "id": "CAMPUS",
    "name": "SUST Campus",
    "type": "destination",
    "gmaps_address": "SUST, Sylhet, Bangladesh"
  }
]

Stores 289 connections between nodes:

[
  {
    "from": "TILAGOR",
    "to": "SHIBGONJ",
    "mode": "bus",
    "route_ids": ["bus1", "bus2"],
    "time_min": 6,
    "distance_meters": 2046,
    "cost": 0,
    "one_way": false
  }
]

Stores 7 bus routes with schedules:

[
  {
    "route_id": "bus1",
    "name": "Bus 1",
    "trips": [
      {
        "trip_id": "bus1_0825",
        "direction": "to_campus",
        "stops": ["TILAGOR", "SHIBGONJ", "CAMPUS"],
        "departure_time": "08:25"
      }
    ]
  }
]

Stores user accounts:

[
  {
    "email": "student@sust.edu",
    "name": "John Doe",
    "created_at": "2026-03-01T10:00:00Z"
  }
]

Stores user’s saved routes:

[
  {
    "id": "fav_123",
    "user_email": "student@sust.edu",
    "name": "Home to Campus",
    "from": "TILAGOR",
    "to": "CAMPUS"
  }
]

Technology Stack

Backend

Runtime: Node.js 18+
Framework: Express.js
Language: TypeScript
API Style: REST
Data Storage: JSON files

Mobile

Framework: Flutter 3.x
Language: Dart
State Management: Provider
Maps: Google Maps Flutter
HTTP: Dio

Web

Framework: React 18
Language: TypeScript
Styling: Tailwind CSS
Maps: Google Maps JavaScript API
Routing: React Router

External APIs

Google Maps Distance Matrix API
Google Maps Geocoding API
Email (for magic link auth)

Deployment Architecture

Backend Deployment

Deploy Node.js API to cloud platform:

Recommended: Railway, Render, or Heroku
Environment Variables: Store API keys, secrets
Port: 3000 (configurable via PORT env var)

Mobile App

Build and distribute Flutter apps:

Android: Google Play Store (.apk or .aab)
iOS: Apple App Store (TestFlight for beta)
Update api_config.dart with backend URL

Web Dashboard

Deploy React app to static hosting:

Options: Vercel, Netlify, GitHub Pages
Build: npm run build → static files
Update API base URL in environment config

Performance Considerations

Graph Loading

Graph data (19 nodes, 289 edges) loads in < 50ms on server startup.

Route Planning

Typical route planning request completes in 100-300ms (without external API calls).

API Caching

Distance Matrix results cached for 7 days, reducing repeated API costs.

Concurrent Users

Node.js handles hundreds of concurrent requests efficiently.

Next Steps

Explore Routing

Learn how the 4 routing strategies work

Graph Model

Understand the network data structure

Transport Modes

Learn about buses, local transport, and walking

API Reference

Explore all API endpoints

​Overview

Node.js Backend

Flutter Mobile

React Web

​High-Level Architecture

​Backend Architecture (Node.js)

​Project Structure

​Core Components

​Mobile App Architecture (Flutter)

​Project Structure

​State Management

​Web Dashboard Architecture (React)

​Key Features

Route Planning

Schedule Browser

Admin Panel

Analytics

​Data Flow

​Route Planning Request Flow

​Authentication Flow (Magic Link)

​File-Based Database

​JSON Data Files

​Technology Stack

Backend

Mobile

Web

External APIs

​Deployment Architecture

​Performance Considerations

Graph Loading

Route Planning

API Caching

Concurrent Users

​Next Steps

Explore Routing

Graph Model

Transport Modes

API Reference

Overview

High-Level Architecture

Backend Architecture (Node.js)

Project Structure

Core Components

Mobile App Architecture (Flutter)

Project Structure

State Management

Web Dashboard Architecture (React)

Key Features

Data Flow

Route Planning Request Flow

Authentication Flow (Magic Link)

File-Based Database

JSON Data Files

Technology Stack

Deployment Architecture

Performance Considerations

Next Steps