# tan-73/urban_nexus architecture

> Architecture diagram of the GitHub repository tan-73/urban_nexus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tan-73/urban_nexus
- Repository: https://github.com/tan-73/urban_nexus

## Overview

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: [`backend/app/main.py`](https://github.com/tan-73/urban_nexus/blob/main/backend/app/main.py) (FastAPI endpoints), [`backend/app/decision.py`](https://github.com/tan-73/urban_nexus/blob/main/backend/app/decision.py) (Intervention candidates), [`backend/app/service.py`](https://github.com/tan-73/urban_nexus/blob/main/backend/app/service.py) (Stateful service), [`frontend/src/App.tsx`](https://github.com/tan-73/urban_nexus/blob/main/frontend/src/App.tsx) (Command center)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator_ui["Operator command center"]
  node_command_center["Command center<br/>[App.tsx]"]
  node_ward_map["Ward map<br/>[WardMap.tsx]"]
  node_trajectories["KPI trajectories<br/>[Trajectory.tsx]"]
  node_http_client["API client<br/>[api.ts]"]
end

subgraph group_api_state["API and ward state"]
  node_http_api["FastAPI endpoints<br/>[main.py]"]
  node_schemas["Request and state schemas<br/>[schemas.py]"]
  node_state_generator["Synthetic ward generator<br/>[generator.py]"]
  node_store[("Ward state store<br/>[db.py]")]
end

subgraph group_analysis["Decision and simulation"]
  node_forecasts["Service forecasts<br/>[domains.py]"]
  node_stress["Stress experiment<br/>[stress.py]"]
  node_routing["Route enumeration<br/>[network.py]"]
  node_candidates["Intervention candidates<br/>[decision.py]"]
  node_evaluation["Feasibility and budget<br/>[decision.py]"]
  node_counterfactual["Coupled simulation and ripple<br/>[simulation.py]"]
end

subgraph group_approval["Approval and records"]
  node_service["Stateful service<br/>[service.py]"]
  node_passport_audit["Passports and audit<br/>[service.py]"]
end

subgraph group_experiments["Optional experiments"]
  node_sumo_experiment["Microscopic traffic experiment<br/>[sumo_adapter.py]"]
  node_matlab_models["MATLAB and Simulink models"]
  node_matlab_validation["MATLAB validation runner<br/>[run_validation.m]"]
end

node_operator(("Ward operator"))
node_sumo_runtime["SUMO runtime"]

node_operator -->|"operates"| node_command_center
node_command_center -->|"requests"| node_http_client
node_http_client -->|"HTTP calls"| node_http_api
node_http_api -->|"validates"| node_schemas
node_http_api -->|"reads state"| node_store
node_http_api -->|"delegates"| node_service
node_http_api -->|"generates state"| node_state_generator
node_http_api -->|"requests forecasts"| node_forecasts
node_http_api -->|"runs stress"| node_stress
node_http_api -->|"requests candidates"| node_candidates
node_http_api -->|"evaluates action"| node_evaluation
node_http_api -->|"computes baseline"| node_counterfactual
node_http_api -->|"serves ward data"| node_ward_map
node_http_api -->|"returns results"| node_command_center
node_service -->|"reads and writes"| node_store
node_service -->|"finds minimum"| node_candidates
node_service -->|"rechecks approval"| node_evaluation
node_service -->|"records decisions"| node_passport_audit
node_state_generator -->|"seeds state"| node_store
node_candidates -->|"enumerates routes"| node_routing
node_candidates -->|"simulates candidates"| node_counterfactual
node_evaluation -->|"simulates action"| node_counterfactual
node_evaluation -->|"selects feasible plan"| node_candidates
node_counterfactual -->|"uses domain models"| node_forecasts
node_counterfactual -->|"computes route metrics"| node_routing
node_stress -->|"starts from generated state"| node_state_generator
node_stress -->|"returns candidate actions"| node_candidates
node_command_center -->|"displays ward"| node_ward_map
node_command_center -->|"displays trajectories"| node_trajectories
node_sumo_experiment -.->|"runs through TraCI"| node_sumo_runtime
node_matlab_validation -.->|"builds and runs"| node_matlab_models

click node_command_center "https://github.com/tan-73/urban_nexus/blob/main/frontend/src/App.tsx"
click node_ward_map "https://github.com/tan-73/urban_nexus/blob/main/frontend/src/WardMap.tsx"
click node_trajectories "https://github.com/tan-73/urban_nexus/blob/main/frontend/src/Trajectory.tsx"
click node_http_client "https://github.com/tan-73/urban_nexus/blob/main/frontend/src/api.ts"
click node_http_api "https://github.com/tan-73/urban_nexus/blob/main/backend/app/main.py"
click node_schemas "https://github.com/tan-73/urban_nexus/blob/main/backend/app/schemas.py"
click node_state_generator "https://github.com/tan-73/urban_nexus/blob/main/backend/app/generator.py"
click node_store "https://github.com/tan-73/urban_nexus/blob/main/backend/app/db.py"
click node_service "https://github.com/tan-73/urban_nexus/blob/main/backend/app/service.py"
click node_forecasts "https://github.com/tan-73/urban_nexus/blob/main/backend/app/domains.py"
click node_stress "https://github.com/tan-73/urban_nexus/blob/main/backend/app/stress.py"
click node_routing "https://github.com/tan-73/urban_nexus/blob/main/backend/app/network.py"
click node_candidates "https://github.com/tan-73/urban_nexus/blob/main/backend/app/decision.py"
click node_evaluation "https://github.com/tan-73/urban_nexus/blob/main/backend/app/decision.py"
click node_counterfactual "https://github.com/tan-73/urban_nexus/blob/main/backend/app/simulation.py"
click node_passport_audit "https://github.com/tan-73/urban_nexus/blob/main/backend/app/service.py"
click node_sumo_experiment "https://github.com/tan-73/urban_nexus/blob/main/backend/app/sumo_adapter.py"
click node_matlab_models "https://github.com/tan-73/urban_nexus/tree/main/matlab"
click node_matlab_validation "https://github.com/tan-73/urban_nexus/blob/main/matlab/run_validation.m"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_command_center,node_ward_map,node_trajectories,node_http_client toneBlue
class node_http_api,node_schemas,node_state_generator,node_store toneAmber
class node_forecasts,node_stress,node_routing,node_candidates,node_evaluation,node_counterfactual toneMint
class node_service,node_passport_audit toneRose
class node_sumo_experiment,node_matlab_models,node_matlab_validation,node_operator,node_sumo_runtime toneIndigo
```

## Components

### Operator command center

- [Command center](https://github.com/tan-73/urban_nexus/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Ward map](https://github.com/tan-73/urban_nexus/blob/main/frontend/src/WardMap.tsx): `frontend/src/WardMap.tsx`
- [KPI trajectories](https://github.com/tan-73/urban_nexus/blob/main/frontend/src/Trajectory.tsx): `frontend/src/Trajectory.tsx`
- [API client](https://github.com/tan-73/urban_nexus/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### API and ward state

- [FastAPI endpoints](https://github.com/tan-73/urban_nexus/blob/main/backend/app/main.py): `backend/app/main.py`
- [Request and state schemas](https://github.com/tan-73/urban_nexus/blob/main/backend/app/schemas.py): `backend/app/schemas.py`
- [Synthetic ward generator](https://github.com/tan-73/urban_nexus/blob/main/backend/app/generator.py): `backend/app/generator.py`
- [Ward state store](https://github.com/tan-73/urban_nexus/blob/main/backend/app/db.py): `backend/app/db.py`

### Decision and simulation

- [Service forecasts](https://github.com/tan-73/urban_nexus/blob/main/backend/app/domains.py): `backend/app/domains.py`
- [Stress experiment](https://github.com/tan-73/urban_nexus/blob/main/backend/app/stress.py): `backend/app/stress.py`
- [Route enumeration](https://github.com/tan-73/urban_nexus/blob/main/backend/app/network.py): `backend/app/network.py`
- [Intervention candidates](https://github.com/tan-73/urban_nexus/blob/main/backend/app/decision.py): `backend/app/decision.py`
- [Feasibility and budget](https://github.com/tan-73/urban_nexus/blob/main/backend/app/decision.py): `backend/app/decision.py`
- [Coupled simulation and ripple](https://github.com/tan-73/urban_nexus/blob/main/backend/app/simulation.py): `backend/app/simulation.py`

### Approval and records

- [Stateful service](https://github.com/tan-73/urban_nexus/blob/main/backend/app/service.py): `backend/app/service.py`
- [Passports and audit](https://github.com/tan-73/urban_nexus/blob/main/backend/app/service.py): `backend/app/service.py`

### Optional experiments

- [Microscopic traffic experiment](https://github.com/tan-73/urban_nexus/blob/main/backend/app/sumo_adapter.py): `backend/app/sumo_adapter.py`
- [MATLAB and Simulink models](https://github.com/tan-73/urban_nexus/tree/main/matlab): `matlab`
- [MATLAB validation runner](https://github.com/tan-73/urban_nexus/blob/main/matlab/run_validation.m): `matlab/run_validation.m`

### Other components

- **Ward operator**
- **SUMO runtime**

## Connections

- 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