Urban Evacuation Bottleneck Simulator – Backend

Spring Boot MVP backend for the Signal Outage Impact Explorer.

What it does

Pick a map area → see all traffic signals → disable a signal or close a road → run a simulation → get:

• Congestion heatmap (per-road-segment congestion intensity)
• Queue buildup at intersections
• Top 5 bottlenecks (auto-identified)
• Metric deltas vs baseline (avg travel time +X%, max queue ×Y)

Supports both regular traffic and evacuation modes (agents flee a disaster radius toward a safe zone).

Architecture

┌─────────────┐    REST / WS     ┌────────────────────┐
│   Frontend   │ ◄──────────────► │  Spring Boot API   │
│  (separate)  │                  │                    │
└─────────────┘                  │  AreaController    │ ──► OsmService (Overpass API)
                                 │  SimulationController│ ──► SimulationEngine
                                 │  WebSocket handler  │ ──► RoutingService (Dijkstra)
                                 └────────────────────┘

Key components

Layer	Class	Purpose
Controller	AreaController	Fetch road network from OSM for a bounding box
Controller	SimulationController	Start simulation, retrieve results
Controller	SimulationWebSocketHandler	Stream live ticks via WebSocket
Service	OsmServiceImpl	Queries Overpass API, parses roads/signals/intersections into a graph
Service	SimulationEngine	Tick-based traffic simulation engine
Service	RoutingService	Dijkstra pathfinding with congestion & disruption penalties
Service	SimulationService	Orchestrates baseline vs disrupted runs, computes metric deltas

API Reference

POST /api/area

Fetch road network for a bounding box.

Request:

{
  "bounds": {
    "south": 40.7480,
    "west": -73.9900,
    "north": 40.7580,
    "east": -73.9750
  }
}

Response: NetworkResponse with networkId, signals, intersections, segments.

GET /api/area/{networkId}/signals

List all traffic signals in a loaded network.

POST /api/simulation

Run a simulation (synchronous, returns final result).

Request:

{
  "networkId": "abc12345",
  "mode": "EVACUATION",
  "durationSeconds": 900,
  "agentCount": 500,
  "disabledSignalIds": [123456789],
  "closedRoadIds": [],
  "disasterLocation": { "lat": 40.753, "lon": -73.982 },
  "disasterRadiusMetres": 1000,
  "disasterType": "FIRE",
  "safeZone": { "lat": 40.760, "lon": -73.970 },
  "runOptimised": false
}

Response: SimulationResultDTO with metrics, heatmap, bottlenecks, delta vs baseline.

GET /api/simulation/{id}

Retrieve a stored simulation result.

GET /api/simulation/{id}/baseline

Retrieve the baseline (no disruptions) result for comparison.

WebSocket: ws://host/ws/simulation

1. Connect
2. Send a SimulationRequest JSON
3. Receive {"type":"tick", "payload": SimulationTickDTO} messages
4. Receive {"type":"result", "payload": SimulationResultDTO} at end

GET /api/health

Health check.

Running

# Requires Java 21+
./mvnw spring-boot:run

# Or build & run
./mvnw package -DskipTests
java -jar target/evacuation-simulator-0.1.0-SNAPSHOT.jar

The server starts on port 8080. CORS is pre-configured for localhost:3000 and localhost:5173.

Configuration

All settings in src/main/resources/application.properties:

Property	Default	Description
osm.overpass.url	Overpass public API	Overpass endpoint
simulation.default-duration-seconds	900	Default sim length
simulation.max-agent-count	5000	Max agents per sim
cors.allowed-origins	localhost:3000,5173	Frontend origins

Tech Stack

• Java 21 + Spring Boot 3.3
• WebFlux WebClient for non-blocking OSM API calls
• WebSocket for real-time tick streaming
• Caffeine cache for OSM response caching
• Dijkstra pathfinding with congestion-aware edge weights
• Tick-based simulation with intersection capacity modeling

Next Steps / TODOs

• AI route suggestion engine (integrate LLM or optimization solver)
• Persist simulations to a database
• Grid-based congestion heatmap generation
• Optimised simulation run (reroute agents using suggested routes)
• Agent grouping (one dot = N people) for large-scale scenarios
• WebSocket connection management and cancellation