# jeremilrk/ai-emergency-response-system architecture

> Architecture diagram of the GitHub repository jeremilrk/ai-emergency-response-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jeremilrk/ai-emergency-response-system
- Repository: https://github.com/jeremilrk/ai-emergency-response-system

## Overview

This is a storm-response planner: a user selects a scenario, and the application loads its road, incident, responder, and evidence data; estimates road conditions and traffic; plans routes; assigns responders; simulates modeled execution; and exports plans and statistics. The graph preserves both Bayesian road inference and historical-traffic routing as distinct capabilities, along with the nearest-responder comparison and plan validation. Edges use README statements and source-index references; unsampled runtime wiring is not inferred beyond those references.

Main entry points: [`run.py`](https://github.com/jeremilrk/ai-emergency-response-system/blob/main/run.py) (Scenario runner), [`emergency_response/loaders.py`](https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/loaders.py) (Input loader), [`emergency_response/simulation.py`](https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/simulation.py) (Response simulation), [`emergency_response/search.py`](https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/search.py) (Path search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Run orchestration"]
  node_runner["Scenario runner<br/>[run.py]"]
  node_scenario["Scenario inputs"]
end

subgraph group_evidence["Scenario evidence"]
  node_loader["Input loader<br/>[loaders.py]"]
  node_records["Domain records<br/>[models.py]"]
  node_road_inference["Road inference<br/>[bayesian.py]"]
  node_traffic_inference["Traffic inference<br/>[hmm.py]"]
end

subgraph group_routing["Route planning"]
  node_graph["Road graph<br/>[graph.py]"]
  node_search["Path search<br/>[search.py]"]
  node_risk_router["Risk routing<br/>[risk_routing.py]"]
  node_traffic_router["Traffic routing<br/>[traffic_routing.py]"]
  node_basic_router["Basic routing<br/>[routing.py]"]
end

subgraph group_dispatch["Dispatch and simulation"]
  node_dispatcher["Assignment optimizer<br/>[allocation.py]"]
  node_nearest["Nearest baseline<br/>[baseline.py]"]
  node_simulator["Response simulation<br/>[simulation.py]"]
  node_sim_records["Execution records"]
  node_scripted["Scripted dispatch<br/>[scripted.py]"]
  node_diagnostics["Decision diagnostics<br/>[diagnostics.py]"]
end

subgraph group_results["Results and validation"]
  node_statistics["Run statistics<br/>[statistics.py]"]
  node_outputs["Plan outputs<br/>[outputs.py]"]
  node_validation["Plan validation<br/>[plan_validation.py]"]
end

node_user(("Planner user"))

node_user -->|"selects scenario"| node_runner
node_runner -->|"loads inputs"| node_loader
node_scenario -->|"provides data"| node_loader
node_loader -->|"builds records"| node_records
node_runner -->|"requests inference"| node_road_inference
node_road_inference -->|"validates probabilities"| node_loader
node_road_inference -->|"reads scenario"| node_records
node_runner -->|"requests inference"| node_traffic_inference
node_traffic_inference -->|"validates probabilities"| node_loader
node_traffic_inference -->|"reads scenario"| node_records
node_runner -->|"selects policy"| node_risk_router
node_risk_router -->|"builds graph"| node_graph
node_risk_router -->|"uses route type"| node_search
node_risk_router -->|"reads scenario"| node_records
node_runner -->|"selects policy"| node_traffic_router
node_traffic_router -->|"uses route search"| node_search
node_traffic_router -->|"uses beliefs"| node_traffic_inference
node_runner -->|"selects policy"| node_basic_router
node_basic_router -->|"uses graph"| node_graph
node_basic_router -->|"reads scenario"| node_records
node_runner -->|"selects search"| node_search
node_search -->|"searches graph"| node_graph
node_runner -->|"selects allocator"| node_dispatcher
node_dispatcher -->|"reads snapshots"| node_sim_records
node_runner -->|"selects baseline"| node_nearest
node_nearest -->|"uses assignment types"| node_dispatcher
node_nearest -->|"reads snapshots"| node_sim_records
node_runner -->|"runs simulation"| node_simulator
node_simulator -->|"copies routing graph"| node_graph
node_simulator -->|"uses route planner"| node_search
node_simulator -->|"creates views"| node_sim_records
node_simulator -->|"records evidence"| node_diagnostics
node_runner -->|"loads script mode"| node_scripted
node_scripted -->|"loads inputs"| node_loader
node_scripted -->|"uses dispatch types"| node_sim_records
node_runner -->|"summarizes run"| node_statistics
node_statistics -->|"summarizes results"| node_sim_records
node_runner -->|"writes results"| node_outputs
node_outputs -->|"formats statistics"| node_statistics
node_outputs -->|"includes diagnostics"| node_diagnostics
node_outputs -->|"checks plans"| node_validation
node_runner -->|"validates plan"| node_validation
node_validation -->|"uses beliefs"| node_road_inference
node_validation -->|"uses metrics"| node_statistics

click node_runner "https://github.com/jeremilrk/ai-emergency-response-system/blob/main/run.py"
click node_scenario "https://github.com/jeremilrk/ai-emergency-response-system/tree/main/Scenarios"
click node_loader "https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/loaders.py"
click node_records "https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/models.py"
click node_road_inference "https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/bayesian.py"
click node_traffic_inference "https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/hmm.py"
click node_graph "https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/graph.py"
click node_search "https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/search.py"
click node_risk_router "https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/risk_routing.py"
click node_traffic_router "https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/traffic_routing.py"
click node_basic_router "https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/routing.py"
click node_dispatcher "https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/allocation.py"
click node_nearest "https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/baseline.py"
click node_simulator "https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/simulation.py"
click node_sim_records "https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/simulation_models.py"
click node_scripted "https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/scripted.py"
click node_diagnostics "https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/diagnostics.py"
click node_statistics "https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/statistics.py"
click node_outputs "https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/outputs.py"
click node_validation "https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/plan_validation.py"

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_runner,node_scenario,node_user toneBlue
class node_loader,node_records,node_road_inference,node_traffic_inference toneAmber
class node_graph,node_search,node_risk_router,node_traffic_router,node_basic_router toneMint
class node_dispatcher,node_nearest,node_simulator,node_sim_records,node_scripted,node_diagnostics toneRose
class node_statistics,node_outputs,node_validation toneIndigo
```

## Components

### Run orchestration

- [Scenario runner](https://github.com/jeremilrk/ai-emergency-response-system/blob/main/run.py): `run.py`
- [Scenario inputs](https://github.com/jeremilrk/ai-emergency-response-system/tree/main/Scenarios): `Scenarios`

### Scenario evidence

- [Input loader](https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/loaders.py): `emergency_response/loaders.py`
- [Domain records](https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/models.py): `emergency_response/models.py`
- [Road inference](https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/bayesian.py): `emergency_response/bayesian.py`
- [Traffic inference](https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/hmm.py): `emergency_response/hmm.py`

### Route planning

- [Road graph](https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/graph.py): `emergency_response/graph.py`
- [Path search](https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/search.py): `emergency_response/search.py`
- [Risk routing](https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/risk_routing.py): `emergency_response/risk_routing.py`
- [Traffic routing](https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/traffic_routing.py): `emergency_response/traffic_routing.py`
- [Basic routing](https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/routing.py): `emergency_response/routing.py`

### Dispatch and simulation

- [Assignment optimizer](https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/allocation.py): `emergency_response/allocation.py`
- [Nearest baseline](https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/baseline.py): `emergency_response/baseline.py`
- [Response simulation](https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/simulation.py): `emergency_response/simulation.py`
- [Execution records](https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/simulation_models.py): `emergency_response/simulation_models.py`
- [Scripted dispatch](https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/scripted.py): `emergency_response/scripted.py`
- [Decision diagnostics](https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/diagnostics.py): `emergency_response/diagnostics.py`

### Results and validation

- [Run statistics](https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/statistics.py): `emergency_response/statistics.py`
- [Plan outputs](https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/outputs.py): `emergency_response/outputs.py`
- [Plan validation](https://github.com/jeremilrk/ai-emergency-response-system/blob/main/emergency_response/plan_validation.py): `emergency_response/plan_validation.py`

### Other components

- **Planner user**

## Connections

- Planner user → Scenario runner: selects scenario (evidence: `README.md`)
- Scenario runner → Input loader: loads inputs (evidence: `run.py`)
- Scenario inputs → Input loader: provides data (evidence: `README.md`)
- Input loader → Domain records: builds records (evidence: `emergency_response/loaders.py`)
- Scenario runner → Road inference: requests inference (evidence: `run.py`)
- Road inference → Input loader: validates probabilities (evidence: `emergency_response/bayesian.py`)
- Road inference → Domain records: reads scenario (evidence: `emergency_response/bayesian.py`)
- Scenario runner → Traffic inference: requests inference (evidence: `run.py`)
- Traffic inference → Input loader: validates probabilities (evidence: `emergency_response/hmm.py`)
- Traffic inference → Domain records: reads scenario (evidence: `emergency_response/hmm.py`)
- Scenario runner → Risk routing: selects policy (evidence: `run.py`)
- Risk routing → Road graph: builds graph (evidence: `emergency_response/risk_routing.py`)
- Risk routing → Path search: uses route type (evidence: `emergency_response/risk_routing.py`)
- Risk routing → Domain records: reads scenario (evidence: `emergency_response/risk_routing.py`)
- Scenario runner → Traffic routing: selects policy (evidence: `run.py`)
- Traffic routing → Path search: uses route search (evidence: `emergency_response/traffic_routing.py`)
- Traffic routing → Traffic inference: uses beliefs (evidence: `emergency_response/traffic_routing.py`)
- Scenario runner → Basic routing: selects policy (evidence: `run.py`)
- Basic routing → Road graph: uses graph (evidence: `emergency_response/routing.py`)
- Basic routing → Domain records: reads scenario (evidence: `emergency_response/routing.py`)
- Scenario runner → Path search: selects search (evidence: `run.py`)
- Path search → Road graph: searches graph (evidence: `emergency_response/search.py`)
- Scenario runner → Assignment optimizer: selects allocator (evidence: `run.py`)
- Assignment optimizer → Execution records: reads snapshots (evidence: `emergency_response/allocation.py`)
- Scenario runner → Nearest baseline: selects baseline (evidence: `run.py`)
- Nearest baseline → Assignment optimizer: uses assignment types (evidence: `emergency_response/baseline.py`)
- Nearest baseline → Execution records: reads snapshots (evidence: `emergency_response/baseline.py`)
- Scenario runner → Response simulation: runs simulation (evidence: `run.py`)
- Response simulation → Road graph: copies routing graph (evidence: `emergency_response/simulation.py`)
- Response simulation → Path search: uses route planner (evidence: `emergency_response/simulation.py`)
- Response simulation → Execution records: creates views (evidence: `emergency_response/simulation.py`)
- Response simulation → Decision diagnostics: records evidence (evidence: `emergency_response/simulation.py`)
- Scenario runner → Scripted dispatch: loads script mode (evidence: `run.py`)
- Scripted dispatch → Input loader: loads inputs (evidence: `emergency_response/scripted.py`)
- Scripted dispatch → Execution records: uses dispatch types (evidence: `emergency_response/scripted.py`)
- Scenario runner → Run statistics: summarizes run (evidence: `run.py`)
- Run statistics → Execution records: summarizes results (evidence: `emergency_response/statistics.py`)
- Scenario runner → Plan outputs: writes results (evidence: `run.py`)
- Plan outputs → Run statistics: formats statistics (evidence: `emergency_response/outputs.py`)
- Plan outputs → Decision diagnostics: includes diagnostics (evidence: `emergency_response/outputs.py`)
- Plan outputs → Plan validation: checks plans (evidence: `emergency_response/outputs.py`)
- Scenario runner → Plan validation: validates plan (evidence: `run.py`)
- Plan validation → Road inference: uses beliefs (evidence: `emergency_response/plan_validation.py`)
- Plan validation → Run statistics: uses metrics (evidence: `emergency_response/plan_validation.py`)