RouteMend

Real-time, multi-modal humanitarian supply-chain routing system with mode-agnostic incremental repair.

Quick Start

With Docker (recommended)

docker-compose up --build

Then open: http://localhost:5173

Manual Start

# 1. PostgreSQL (must be running on localhost:5432)
createdb -U postgres routemend

# 2. Spring Boot backend
cd backend
mvn spring-boot:run

# 3. Node.js gateway
cd gateway
npm install
npm start

# 4. React frontend
cd frontend
npm install
npm run dev

Architecture

React + Leaflet  <──WebSocket──>  Node.js Gateway  <──HTTP──>  Spring Boot  <──JPA──>  PostgreSQL

• Node.js has ZERO routing logic — pure relay
• Spring Boot owns all algorithms and state
• PostgreSQL is the single source of truth

Key Design: Mode-Agnosticism

The repair algorithm (BoundedRepairSearch) never branches on mode == ROAD etc. Mode awareness lives in exactly one class: CarrierModeFilter.java.

// The entire repair call — same for ROAD, SEA, and AIR
BoundedRepairSearch.repair(graph, currentNode, dest, blockedRouteId,
    CarrierModeFilter.edgeFilter(carrier.type),   // ← only mode-aware line
    maxHops=5, hubNodes, altModeFilter)

Demo Script

1. Open http://localhost:5173
2. Click ▶ Start to begin carrier movement
3. Click a brown (ROAD) polyline — watch only road carriers react
4. Click a blue (SEA) polyline — same repair function, sea carriers only
5. Click a purple dashed (AIR) polyline — same again
6. Check stats panel: repair time vs full-recompute estimate, nodes touched (K)
7. If usedModeSwitchFallback: true fires → mode-switch badge appears

Graph: "Adriano Coast"

• 31 nodes: 2 depots, 18 villages, 4 ports, 4 airports, 3 logistics hubs
• 62 routes: 28 ROAD + 19 SEA + 15 AIR
• 16 carriers: 8 trucks, 4 ships, 4 planes
• 8 shipments (4 multi-modal, 4 single-mode)

Stretch Features Included

• 12a HALT-first protocol: carriers halt before repair starts
• 12b Hub transfer capacity: ports/airports can be destroyed
• 12c Mode-conditional weather: fog grounds AIR, slows ROAD, spares SEA
• 12d Threat-weighted edges: effectiveWeight() single function
• 12e Dynamic load balancing: cost rises as edges fill up

Tech Stack

Layer	Tech
Frontend	React 18 + Leaflet.js + Socket.IO client
Gateway	Node.js 20 + Express + Socket.IO
Engine	Java 17 + Spring Boot 3.2 + Spring Data JPA
Database	PostgreSQL 15
Infra	Docker Compose

Running Tests

cd backend
mvn test