# jack-schultz/evacuation-simulation architecture

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

- Interactive diagram: https://gitdiagram.com/jack-schultz/evacuation-simulation
- Repository: https://github.com/jack-schultz/evacuation-simulation

## Overview

Evacuation Simulation lets planners edit and save building layouts, configure hazards and occupants, then run a server-computed evacuation estimate and play its frames while reviewing results. The graph follows the documented editor-to-run workflow and sampled orchestration; the README also documents navigation, congestion and persistence capabilities. The API route implementations and several simulation internals were not sampled, so uncertain wiring among those components is omitted.

Main entry points: [`backend/app/services/simulation_service.py`](https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/services/simulation_service.py) (Simulation service), [`backend/app/simulation/engine.py`](https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/simulation/engine.py) (Simulation engine), [`frontend/src/services/api.ts`](https://github.com/jack-schultz/evacuation-simulation/blob/main/frontend/src/services/api.ts) (HTTP client), [`frontend/src/App.tsx`](https://github.com/jack-schultz/evacuation-simulation/blob/main/frontend/src/App.tsx) (Editor application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Planning interface"]
  node_app["Editor application<br/>[App.tsx]"]
  node_canvas["Layout canvas<br/>[index.tsx]"]
  node_editor["Editor state"]
  node_persistence["Building persistence"]
  node_session["Simulation session"]
  node_playback["Frame playback"]
  node_resultsui["Controls and results<br/>[ResultsPanel.tsx]"]
  node_client["HTTP client<br/>[api.ts]"]
end

subgraph group_api["Backend API"]
  node_server["FastAPI application<br/>[main.py]"]
  node_buildingapi["Building endpoints<br/>[buildings.py]"]
  node_simapi["Simulation endpoints<br/>[simulations.py]"]
  node_buildingservice["Building service"]
  node_simservice["Simulation service"]
end

subgraph group_domain["Simulation domain"]
  node_layout["Building layout<br/>[layout.py]"]
  node_graph["Navigation graph<br/>[graph.py]"]
  node_routing["Shortest-path routing<br/>[routing.py]"]
  node_engine["Simulation engine<br/>[engine.py]"]
  node_step["Timestep movement<br/>[step.py]"]
  node_flow["Capacity flow<br/>[flow.py]"]
  node_simresults["Frames and statistics<br/>[results.py]"]
end

subgraph group_storage["Persistence"]
  node_buildingrecords[("Building records<br/>[building.py]")]
  node_simrecords[("Simulation records<br/>[building.py]")]
  node_database[("SQLite database<br/>[database.py]")]
end

node_planner(("Building planner"))

node_planner -->|"edits layout"| node_app
node_app -->|"renders editor"| node_canvas
node_canvas -->|"updates layout"| node_editor
node_app -->|"saves building"| node_persistence
node_app -->|"starts run"| node_session
node_persistence -->|"requests buildings"| node_client
node_session -->|"creates and runs"| node_client
node_playback -->|"supplies playback"| node_resultsui
node_client -->|"HTTP requests"| node_server
node_server -->|"dispatches"| node_buildingapi
node_server -->|"dispatches"| node_simapi
node_buildingapi -->|"handles CRUD"| node_buildingservice
node_simapi -->|"handles runs"| node_simservice
node_buildingservice -->|"reads and writes"| node_buildingrecords
node_simservice -->|"loads layout"| node_buildingservice
node_simservice -->|"reads and writes"| node_simrecords
node_buildingrecords -->|"stored in"| node_database
node_simrecords -->|"stored in"| node_database
node_buildingservice -->|"validates layout"| node_layout
node_simservice -->|"runs model"| node_engine
node_engine -->|"builds navigation"| node_graph
node_engine -->|"selects routes"| node_routing
node_engine -->|"advances occupants"| node_step
node_step -->|"uses capacity model"| node_flow
node_engine -->|"builds output"| node_simresults
node_simservice -->|"persists frames and results"| node_simresults
node_simservice -->|"returns frames and results"| node_client
node_client -->|"delivers run response"| node_session
node_session -->|"loads frames"| node_playback

click node_app "https://github.com/jack-schultz/evacuation-simulation/blob/main/frontend/src/App.tsx"
click node_canvas "https://github.com/jack-schultz/evacuation-simulation/blob/main/frontend/src/components/BuildingCanvas/index.tsx"
click node_editor "https://github.com/jack-schultz/evacuation-simulation/blob/main/frontend/src/hooks/useBuildingEditor.ts"
click node_persistence "https://github.com/jack-schultz/evacuation-simulation/blob/main/frontend/src/hooks/useBuildingPersistence.ts"
click node_session "https://github.com/jack-schultz/evacuation-simulation/blob/main/frontend/src/hooks/useSimulationSession.ts"
click node_playback "https://github.com/jack-schultz/evacuation-simulation/blob/main/frontend/src/simulation/useSimulationPlayback.ts"
click node_resultsui "https://github.com/jack-schultz/evacuation-simulation/blob/main/frontend/src/components/ResultsPanel.tsx"
click node_client "https://github.com/jack-schultz/evacuation-simulation/blob/main/frontend/src/services/api.ts"
click node_server "https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/main.py"
click node_buildingapi "https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/api/buildings.py"
click node_simapi "https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/api/simulations.py"
click node_buildingservice "https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/services/building_service.py"
click node_simservice "https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/services/simulation_service.py"
click node_layout "https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/domain/building/layout.py"
click node_graph "https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/simulation/graph.py"
click node_routing "https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/simulation/routing.py"
click node_engine "https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/simulation/engine.py"
click node_step "https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/simulation/step.py"
click node_flow "https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/simulation/flow.py"
click node_simresults "https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/simulation/results.py"
click node_buildingrecords "https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/models/building.py"
click node_simrecords "https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/models/building.py"
click node_database "https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/core/database.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_app,node_canvas,node_editor,node_persistence,node_session,node_playback,node_resultsui,node_client toneBlue
class node_server,node_buildingapi,node_simapi,node_buildingservice,node_simservice toneAmber
class node_layout,node_graph,node_routing,node_engine,node_step,node_flow,node_simresults toneMint
class node_buildingrecords,node_simrecords,node_database toneRose
class node_planner toneIndigo
```

## Components

### Planning interface

- [Editor application](https://github.com/jack-schultz/evacuation-simulation/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Layout canvas](https://github.com/jack-schultz/evacuation-simulation/blob/main/frontend/src/components/BuildingCanvas/index.tsx): `frontend/src/components/BuildingCanvas/index.tsx`
- [Editor state](https://github.com/jack-schultz/evacuation-simulation/blob/main/frontend/src/hooks/useBuildingEditor.ts): `frontend/src/hooks/useBuildingEditor.ts`
- [Building persistence](https://github.com/jack-schultz/evacuation-simulation/blob/main/frontend/src/hooks/useBuildingPersistence.ts): `frontend/src/hooks/useBuildingPersistence.ts`
- [Simulation session](https://github.com/jack-schultz/evacuation-simulation/blob/main/frontend/src/hooks/useSimulationSession.ts): `frontend/src/hooks/useSimulationSession.ts`
- [Frame playback](https://github.com/jack-schultz/evacuation-simulation/blob/main/frontend/src/simulation/useSimulationPlayback.ts): `frontend/src/simulation/useSimulationPlayback.ts`
- [Controls and results](https://github.com/jack-schultz/evacuation-simulation/blob/main/frontend/src/components/ResultsPanel.tsx): `frontend/src/components/ResultsPanel.tsx`
- [HTTP client](https://github.com/jack-schultz/evacuation-simulation/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### Backend API

- [FastAPI application](https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/main.py): `backend/app/main.py`
- [Building endpoints](https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/api/buildings.py): `backend/app/api/buildings.py`
- [Simulation endpoints](https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/api/simulations.py): `backend/app/api/simulations.py`
- [Building service](https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/services/building_service.py): `backend/app/services/building_service.py`
- [Simulation service](https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/services/simulation_service.py): `backend/app/services/simulation_service.py`

### Simulation domain

- [Building layout](https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/domain/building/layout.py): `backend/app/domain/building/layout.py`
- [Navigation graph](https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/simulation/graph.py): `backend/app/simulation/graph.py`
- [Shortest-path routing](https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/simulation/routing.py): `backend/app/simulation/routing.py`
- [Simulation engine](https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/simulation/engine.py): `backend/app/simulation/engine.py`
- [Timestep movement](https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/simulation/step.py): `backend/app/simulation/step.py`
- [Capacity flow](https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/simulation/flow.py): `backend/app/simulation/flow.py`
- [Frames and statistics](https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/simulation/results.py): `backend/app/simulation/results.py`

### Persistence

- [Building records](https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/models/building.py): `backend/app/models/building.py`
- [Simulation records](https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/models/building.py): `backend/app/models/building.py`
- [SQLite database](https://github.com/jack-schultz/evacuation-simulation/blob/main/backend/app/core/database.py): `backend/app/core/database.py`

### Other components

- **Building planner**

## Connections

- Building planner → Editor application: edits layout
- Editor application → Layout canvas: renders editor
- Layout canvas → Editor state: updates layout
- Editor application → Building persistence: saves building
- Editor application → Simulation session: starts run
- Building persistence → HTTP client: requests buildings
- Simulation session → HTTP client: creates and runs
- Frame playback → Controls and results: supplies playback
- HTTP client → FastAPI application: HTTP requests
- FastAPI application → Building endpoints: dispatches
- FastAPI application → Simulation endpoints: dispatches
- Building endpoints → Building service: handles CRUD
- Simulation endpoints → Simulation service: handles runs
- Building service → Building records: reads and writes
- Simulation service → Building service: loads layout
- Simulation service → Simulation records: reads and writes
- Building records → SQLite database: stored in
- Simulation records → SQLite database: stored in
- Building service → Building layout: validates layout
- Simulation service → Simulation engine: runs model
- Simulation engine → Navigation graph: builds navigation
- Simulation engine → Shortest-path routing: selects routes
- Simulation engine → Timestep movement: advances occupants
- Timestep movement → Capacity flow: uses capacity model
- Simulation engine → Frames and statistics: builds output
- Simulation service → Frames and statistics: persists frames and results
- Simulation service → HTTP client: returns frames and results
- HTTP client → Simulation session: delivers run response
- Simulation session → Frame playback: loads frames