MESHCUE

Mesh-based Emergency Smart Healthcare Coordination & Urgent Emergency response.

MESHCUE is a research platform for getting ambulances to patients faster. Instead of relying on sirens (which only clear traffic a few metres ahead) or blindly rerouting around jams (often slower than the jam itself), it messages the drivers in the ambulance's path so the corridor clears ahead of it — and it decides, per situation, whether clearing the corridor or rerouting actually gets there sooner.

It runs on a real OpenStreetMap road network (Tiruchirappalli, with real hospitals) inside a tick-based traffic simulator, and every decision the system makes is explainable, reproducible, and measured against simulated ground truth.

---

Highlights

• Live map on real roads — the simulator drives vehicles along the actual OSM street network (64k+ intersections), honouring road class, speed limits, lanes and one-way streets. Hospitals are real, with live bed availability.
• Explainable dispatch — when an emergency is created, the system picks the nearest available unit (parked at a hospital or already roaming) and shows why, with the distances it compared.
• Clear-the-corridor vs. reroute — congestion ahead triggers alerts to nearby app users, who pull aside to open a lane; the routing logic holds the route when the corridor will clear in time, and reroutes only when a road is genuinely impassable — narrating the ETA arithmetic behind each choice.
• Scenario player + cinematic mode — six built-in scenarios (clearable traffic, hard block, accident-on-route, congested return, rush hour, multi-hazard), plus a cinematic camera that follows the ambulance with on-map narration for presentations.
• Research-grade guarantees — every decision is recorded and explainable; runs are deterministic from a seed and fully replayable; the true occupancy of each vehicle is readable only by the evaluation scorer, so models are graded against data they never saw; and no threshold is hardcoded — all come from the config service.

Quick start

Two terminals (Windows). See QUICKSTART.md for details.

.\scripts\start.cmd     # 1) backend (Docker) + seeds the operator account
.\scripts\rcc.cmd       # 2) the Research Control Center UI

Then open http://localhost:3000/map.

Cross-platform with Docker + Make:

cp .env.example .env
make up          # build + start everything
make smoke       # health-check every service + the UI

Architecture

A gateway-fronted set of 22 FastAPI microservices and 4 front-ends, wired over an event broker with a WebSocket realtime layer.

• Foundation — API gateway (single entry, role-enforced), configuration/experiments, event broker + realtime WebSocket gateway, shared contracts.
• Domain core — emergency lifecycle, user manager, telemetry ingest, and the traffic simulator (digital twin).
• Decision pipeline — occupancy → traffic → route → corridor → signal preemption → multi-ambulance coordination → citizen alerting → voice.
• Research layer — evaluation harness, recording/replay, explainability, analytics, and fault-injection testing.
• Front-ends — Research Control Center and Dispatcher (Next.js), Citizen and Driver apps (React Native / Expo).

Tech stack

Python · FastAPI · Next.js / React / TypeScript · React Native (Expo) · PostgreSQL + PostGIS · TimescaleDB · Redis · WebSockets · Docker Compose · MapLibre GL · OpenStreetMap.

Repository layout

services/   22 FastAPI microservices
apps/       research-control-center, dispatcher, citizen-app, driver
libs/       shared Python libraries (contracts, auth, broker, persistence, ...)
deploy/     Dockerfiles for the shared base + per-service images
scripts/    start/stop helpers, the OSM road-network fetcher, E2E checks
db/         SQL schema

Notes (development defaults)

• The dev JWT secret is shared and insecure — override MESHCUE_JWT_SECRET before any real deployment.
• The default event broker is in-memory: services are individually healthy but events don't cross service boundaries. For real cross-service flow, set PUBLISHER_BACKEND=redis + BROKER_URL=redis://redis:6379 and use the data/full profile.
• The Tiruchirappalli road network (services/simulation-engine/.../data/roads.json) is bundled so the simulator runs offline. Regenerate or widen it with scripts/fetch_osm_roads.py.