How tan-73/urban_nexus works
UrbanNexus is a synthetic ward-level decision-support application, not a municipal control system. An operator uses the React command center to inspect ward conditions, run a stress scenario, compare forecasts and candidate interventions, and review cross-service impacts and safety constraints. If an intervention passes, the operator can approve its Action Passport; the backend rechecks it and simulates an updated ward state while recording an audit trail. The README also documents separate SUMO experiments and authored MATLAB/Simulink parity work. Backend details are based on sampled source; those optional integration links are shown only where documented.
Main entry points: main.py FastAPI endpoints · decision.py Intervention candidates · service.py Stateful service · App.tsx Command center
Components 21
Operator command center
- Command center
frontend/src/App.tsx - Ward map
frontend/src/WardMap.tsx - KPI trajectories
frontend/src/Trajectory.tsx - API client
frontend/src/api.ts
API and ward state
- FastAPI endpoints
backend/app/main.py - Request and state schemas
backend/app/schemas.py - Synthetic ward generator
backend/app/generator.py - Ward state store
backend/app/db.py
Decision and simulation
- Service forecasts
backend/app/domains.py - Stress experiment
backend/app/stress.py - Route enumeration
backend/app/network.py - Intervention candidates
backend/app/decision.py - Feasibility and budget
backend/app/decision.py - Coupled simulation and ripple
backend/app/simulation.py
Approval and records
- Stateful service
backend/app/service.py - Passports and audit
backend/app/service.py
Optional experiments
- Microscopic traffic experiment
backend/app/sumo_adapter.py - MATLAB and Simulink models
matlab - MATLAB validation runner
matlab/run_validation.m
Other components
- Ward operator
- SUMO runtime
Connections 31
- Ward operator → Command center: operates
- Command center → API client: requests
- API client → FastAPI endpoints: HTTP calls
- FastAPI endpoints → Request and state schemas: validates
- FastAPI endpoints → Ward state store: reads state
- FastAPI endpoints → Stateful service: delegates
- FastAPI endpoints → Synthetic ward generator: generates state
- FastAPI endpoints → Service forecasts: requests forecasts
- FastAPI endpoints → Stress experiment: runs stress
- FastAPI endpoints → Intervention candidates: requests candidates
- FastAPI endpoints → Feasibility and budget: evaluates action
- FastAPI endpoints → Coupled simulation and ripple: computes baseline
- FastAPI endpoints → Ward map: serves ward data
- FastAPI endpoints → Command center: returns results
- Stateful service → Ward state store: reads and writes
- Stateful service → Intervention candidates: finds minimum
- Stateful service → Feasibility and budget: rechecks approval
- Stateful service → Passports and audit: records decisions
- Synthetic ward generator → Ward state store: seeds state
- Intervention candidates → Route enumeration: enumerates routes
- Intervention candidates → Coupled simulation and ripple: simulates candidates
- Feasibility and budget → Coupled simulation and ripple: simulates action
- Feasibility and budget → Intervention candidates: selects feasible plan
- Coupled simulation and ripple → Service forecasts: uses domain models
- Coupled simulation and ripple → Route enumeration: computes route metrics
- Stress experiment → Synthetic ward generator: starts from generated state
- Stress experiment → Intervention candidates: returns candidate actions
- Command center → Ward map: displays ward
- Command center → KPI trajectories: displays trajectories
- Microscopic traffic experiment → SUMO runtime: runs through TraCI
- MATLAB validation runner → MATLAB and Simulink models: builds and runs