Backend Setup

Deploy and configure the MND Node.js/TypeScript backend

Overview

The MND backend is built with Node.js, TypeScript, and Express. It provides a graph-based routing engine with Google Distance Matrix API integration.

Prerequisites

• Node.js 18+ and npm
• Git
• PM2 (for production)
• Google Distance Matrix API key

Installation

1. Clone and Navigate

cd MND-backend

2. Install Dependencies

npm install

Core dependencies:

• express - Web framework
• cors - Cross-origin resource sharing
• dotenv - Environment variables
• axios - HTTP client for Google APIs

Dev dependencies:

• typescript - TypeScript compiler
• tsx - TypeScript execution
• @types/* - Type definitions

3. Configure Environment

Copy the example environment file:

cp .env.example .env

Edit .env with your configuration:

GOOGLE_DM_API_KEY=your_google_api_key_here
PORT=3000
NODE_ENV=production

See Environment Variables for all options.

Building for Production

Compile TypeScript

The TypeScript compiler is configured in tsconfig.json:

npm run build

This compiles src/**/*.ts to dist/**/*.js with:

• Target: ES2022
• Module: CommonJS
• Source maps enabled
• Strict type checking

Build output:

MND-backend/
├── dist/
│   ├── server.js
│   ├── server.js.map
│   ├── core/
│   │   ├── graph.js
│   │   ├── planner.js
│   │   └── auth.js
│   ├── api/
│   │   ├── routesController.js
│   │   ├── authController.js
│   │   └── ...
│   └── infra/
│       └── distanceMatrixClient.js

Verify Build

node dist/server.js

Running in Production

Option 1: Direct Node Execution

NODE_ENV=production node dist/server.js

Option 2: PM2 Process Manager (Recommended)

Install PM2 globally:

npm install -g pm2

Start the application:

pm2 start dist/server.js --name mnd-backend

PM2 configuration file (ecosystem.config.js):

module.exports = {
  apps: [{
    name: 'mnd-backend',
    script: './dist/server.js',
    instances: 1,
    exec_mode: 'fork',
    env: {
      NODE_ENV: 'production',
      PORT: 3000
    },
    error_file: './logs/err.log',
    out_file: './logs/out.log',
    log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
    autorestart: true,
    max_restarts: 10,
    min_uptime: '10s'
  }]
}

Start with config:

pm2 start ecosystem.config.js

PM2 Commands

# View status
pm2 status

# View logs
pm2 logs mnd-backend

# Restart
pm2 restart mnd-backend

# Stop
pm2 stop mnd-backend

# Delete from PM2
pm2 delete mnd-backend

# Auto-start on system boot
pm2 startup
pm2 save

Port Configuration

The server listens on port 3000 by default (configurable via PORT env var).

Bind to all network interfaces:

The server is configured to listen on 0.0.0.0 for cross-device access:

// src/server.ts:153
app.listen(PORT, '0.0.0.0', () => {
  console.log(`Server running on http://localhost:${PORT}`);
  console.log(`Network access: http://${networkIP}:${PORT}`);
});

Firewall configuration (Ubuntu/Debian):

sudo ufw allow 3000/tcp
sudo ufw reload

Windows Firewall:

Allow inbound connections on port 3000 through Windows Defender Firewall.

Network Access

The server automatically detects and displays the network IP:

🚌 University Bus Routing API

Loading graph data...

✓ Server running on http://localhost:3000
✓ Network access: http://192.168.1.100:3000

📱 Access from mobile/other devices (same WiFi):
   Health check: http://192.168.1.100:3000/api/health
   Example route: http://192.168.1.100:3000/api/routes?from=TILAGOR&to=CAMPUS&time=08:30

Health Checks

Verify the server is running:

curl http://localhost:3000/api/health

Response:

{
  "status": "ok",
  "uptime": 12345.67,
  "timestamp": "2026-03-05T10:30:00.000Z"
}

API Endpoints

Full endpoint list:

curl http://localhost:3000/api/info

Core endpoints:

• GET /api/health - Health check
• GET /api/nodes - List all locations
• GET /api/routes/list - List all bus routes
• GET /api/routes?from=X&to=Y&time=HH:MM - Plan a route

Auth endpoints:

• POST /api/auth/send-link - Send magic link
• GET /api/auth/verify?token=X - Verify magic link
• GET /api/profile - Get user profile

Favorites (requires auth):

• GET /api/favorites - List favorites
• POST /api/favorites - Add favorite
• PUT /api/favorites/:id - Update favorite
• DELETE /api/favorites/:id - Delete favorite

Bus schedules:

• GET /api/buses/upcoming?from=X - Upcoming buses
• GET /api/buses/schedule/:routeId - Route schedule
• GET /api/routes/:routeId - Route details

Data Files

The graph data is loaded on startup from:

MND-backend/src/data/
├── nodes.json     # Locations and stops
├── edges.json     # Connections between nodes
└── routes.json    # Bus route schedules

See Data Configuration for editing these files.

Troubleshooting

Build Errors

# Clean build
rm -rf dist/
npm run build

Port Already in Use

# Find process using port 3000
lsof -i :3000
# Or on Windows:
netstat -ano | findstr :3000

# Kill the process
kill -9 <PID>

Module Not Found

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

Cannot Access from Other Devices

1. Check firewall settings
2. Verify devices are on same network
3. Use network IP (not localhost) from other devices
4. Ensure server is binding to 0.0.0.0, not 127.0.0.1

Production Checklist

• Environment variables configured
• Google Distance Matrix API key set
• TypeScript compiled successfully
• PM2 process running
• Health check endpoint responds
• Firewall allows port 3000
• PM2 configured for auto-restart on boot
• Log rotation configured
• Data files are up to date
• API quota monitoring enabled

Next Steps

• Configure Environment Variables
• Set up Google APIs
• Configure Data Files
• Deploy Frontend