# krutikap469-oss/krutika architecture

> Architecture diagram of the GitHub repository krutikap469-oss/krutika, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/krutikap469-oss/krutika
- Repository: https://github.com/krutikap469-oss/krutika

## Overview

PulseRoute AI is a rural emergency dispatch and routing application. A patient or operator submits an emergency through the web UI; the frontend sends it to the API, where network state coordinates triage, facility/ambulance matching, and route selection. The UI then presents the decision and live network telemetry. The graph also preserves documented scenario, road-block, driver-message, audit, and benchmark capabilities. Some backend and UI wiring is only partially excerpted; edges are included only where the excerpts, SOURCE INDEX, or README support them.

Main entry points: [`backend/main.py`](https://github.com/krutikap469-oss/krutika/blob/main/backend/main.py) (FastAPI endpoints), [`frontend/src/App.jsx`](https://github.com/krutikap469-oss/krutika/blob/main/frontend/src/App.jsx) (Dispatch workspace), [`backend/state/network_state.py`](https://github.com/krutikap469-oss/krutika/blob/main/backend/state/network_state.py) (Dispatch coordinator), [`frontend/src/hooks/useNetworkState.js`](https://github.com/krutikap469-oss/krutika/blob/main/frontend/src/hooks/useNetworkState.js) (Network client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dispatch interface"]
  node_app["Dispatch workspace<br/>[App.jsx]"]
  node_emergency["Emergency intake<br/>[EmergencyModal.jsx]"]
  node_scenario["Scenario controls<br/>[ScenarioBar.jsx]"]
  node_map["Network map<br/>[MapView.jsx]"]
  node_telemetry["GPS telemetry<br/>[Telemetry.jsx]"]
  node_decision["Decision log<br/>[DecisionLog.jsx]"]
  node_benchmark_ui["Benchmark view<br/>[BenchmarkModal.jsx]"]
  node_client_state["Network client<br/>[useNetworkState.js]"]
end

subgraph group_api["API and orchestration"]
  node_api["FastAPI endpoints<br/>[main.py]"]
end

subgraph group_routing["Dispatch and routing"]
  node_generator["District network generator<br/>[generator.py]"]
  node_matcher["Constraint and cost matcher<br/>[matcher.py]"]
  node_router["A* / Dijkstra router<br/>[router.py]"]
  node_graph["Road graph<br/>[graph.py]"]
end

subgraph group_state["Network state"]
  node_manager["Dispatch coordinator<br/>[network_state.py]"]
  node_audit[("Dispatch audit store<br/>[db.py]")]
end

node_patient(("Patient / operator"))
node_service(("Backend service"))

node_patient -->|"reports emergency"| node_emergency
node_app -->|"presents"| node_emergency
node_app -->|"renders"| node_scenario
node_app -->|"renders"| node_map
node_app -->|"renders"| node_telemetry
node_app -->|"renders"| node_decision
node_app -->|"renders"| node_benchmark_ui
node_app -->|"uses"| node_client_state
node_emergency -.->|"submits"| node_client_state
node_scenario -->|"triggers"| node_client_state
node_client_state -->|"calls REST"| node_api
node_client_state -->|"opens WebSocket"| node_api
node_api -->|"dispatches request"| node_manager
node_api -->|"routes scenarios"| node_manager
node_api -->|"toggles road"| node_manager
node_api -->|"forwards messages"| node_manager
node_manager -->|"seeds network"| node_generator
node_manager -->|"matches candidates"| node_matcher
node_manager -->|"routes trips"| node_router
node_matcher -->|"evaluates paths"| node_router
node_matcher -->|"reads network"| node_graph
node_router -->|"traverses"| node_graph
node_generator -->|"builds roads"| node_graph
node_api -->|"benchmarks paths"| node_router
node_manager -->|"records dispatches"| node_audit
node_api -->|"reads logs"| node_audit
node_service -.->|"serves requests"| node_api
node_api -->|"streams telemetry"| node_client_state
node_client_state -->|"provides state"| node_app

click node_app "https://github.com/krutikap469-oss/krutika/blob/main/frontend/src/App.jsx"
click node_emergency "https://github.com/krutikap469-oss/krutika/blob/main/frontend/src/components/EmergencyModal.jsx"
click node_scenario "https://github.com/krutikap469-oss/krutika/blob/main/frontend/src/components/ScenarioBar.jsx"
click node_map "https://github.com/krutikap469-oss/krutika/blob/main/frontend/src/components/MapView.jsx"
click node_telemetry "https://github.com/krutikap469-oss/krutika/blob/main/frontend/src/components/Telemetry.jsx"
click node_decision "https://github.com/krutikap469-oss/krutika/blob/main/frontend/src/components/DecisionLog.jsx"
click node_benchmark_ui "https://github.com/krutikap469-oss/krutika/blob/main/frontend/src/components/BenchmarkModal.jsx"
click node_client_state "https://github.com/krutikap469-oss/krutika/blob/main/frontend/src/hooks/useNetworkState.js"
click node_api "https://github.com/krutikap469-oss/krutika/blob/main/backend/main.py"
click node_manager "https://github.com/krutikap469-oss/krutika/blob/main/backend/state/network_state.py"
click node_generator "https://github.com/krutikap469-oss/krutika/blob/main/backend/core/generator.py"
click node_matcher "https://github.com/krutikap469-oss/krutika/blob/main/backend/core/matcher.py"
click node_router "https://github.com/krutikap469-oss/krutika/blob/main/backend/core/router.py"
click node_graph "https://github.com/krutikap469-oss/krutika/blob/main/backend/core/graph.py"
click node_audit "https://github.com/krutikap469-oss/krutika/blob/main/backend/state/db.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_emergency,node_scenario,node_map,node_telemetry,node_decision,node_benchmark_ui,node_client_state toneBlue
class node_api toneAmber
class node_generator,node_matcher,node_router,node_graph toneMint
class node_manager,node_audit toneRose
class node_patient,node_service toneIndigo
```

## Components

### Dispatch interface

- [Dispatch workspace](https://github.com/krutikap469-oss/krutika/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Emergency intake](https://github.com/krutikap469-oss/krutika/blob/main/frontend/src/components/EmergencyModal.jsx): `frontend/src/components/EmergencyModal.jsx`
- [Scenario controls](https://github.com/krutikap469-oss/krutika/blob/main/frontend/src/components/ScenarioBar.jsx): `frontend/src/components/ScenarioBar.jsx`
- [Network map](https://github.com/krutikap469-oss/krutika/blob/main/frontend/src/components/MapView.jsx): `frontend/src/components/MapView.jsx`
- [GPS telemetry](https://github.com/krutikap469-oss/krutika/blob/main/frontend/src/components/Telemetry.jsx): `frontend/src/components/Telemetry.jsx`
- [Decision log](https://github.com/krutikap469-oss/krutika/blob/main/frontend/src/components/DecisionLog.jsx): `frontend/src/components/DecisionLog.jsx`
- [Benchmark view](https://github.com/krutikap469-oss/krutika/blob/main/frontend/src/components/BenchmarkModal.jsx): `frontend/src/components/BenchmarkModal.jsx`
- [Network client](https://github.com/krutikap469-oss/krutika/blob/main/frontend/src/hooks/useNetworkState.js): `frontend/src/hooks/useNetworkState.js`

### API and orchestration

- [FastAPI endpoints](https://github.com/krutikap469-oss/krutika/blob/main/backend/main.py): `backend/main.py`

### Dispatch and routing

- [District network generator](https://github.com/krutikap469-oss/krutika/blob/main/backend/core/generator.py): `backend/core/generator.py`
- [Constraint and cost matcher](https://github.com/krutikap469-oss/krutika/blob/main/backend/core/matcher.py): `backend/core/matcher.py`
- [A* / Dijkstra router](https://github.com/krutikap469-oss/krutika/blob/main/backend/core/router.py): `backend/core/router.py`
- [Road graph](https://github.com/krutikap469-oss/krutika/blob/main/backend/core/graph.py): `backend/core/graph.py`

### Network state

- [Dispatch coordinator](https://github.com/krutikap469-oss/krutika/blob/main/backend/state/network_state.py): `backend/state/network_state.py`
- [Dispatch audit store](https://github.com/krutikap469-oss/krutika/blob/main/backend/state/db.py): `backend/state/db.py`

### Other components

- **Patient / operator**
- **Backend service**

## Connections

- Patient / operator → Emergency intake: reports emergency (evidence: `README.md`)
- Dispatch workspace → Emergency intake: presents (evidence: `frontend/src/App.jsx`)
- Dispatch workspace → Scenario controls: renders (evidence: `frontend/src/App.jsx`)
- Dispatch workspace → Network map: renders (evidence: `frontend/src/App.jsx`)
- Dispatch workspace → GPS telemetry: renders (evidence: `frontend/src/App.jsx`)
- Dispatch workspace → Decision log: renders (evidence: `frontend/src/App.jsx`)
- Dispatch workspace → Benchmark view: renders (evidence: `frontend/src/App.jsx`)
- Dispatch workspace → Network client: uses (evidence: `frontend/src/App.jsx`)
- Emergency intake → Network client: submits
- Scenario controls → Network client: triggers (evidence: `frontend/src/App.jsx`)
- Network client → FastAPI endpoints: calls REST (evidence: `frontend/src/hooks/useNetworkState.js`)
- Network client → FastAPI endpoints: opens WebSocket (evidence: `frontend/src/hooks/useNetworkState.js`)
- FastAPI endpoints → Dispatch coordinator: dispatches request (evidence: `backend/main.py`)
- FastAPI endpoints → Dispatch coordinator: routes scenarios (evidence: `backend/main.py`)
- FastAPI endpoints → Dispatch coordinator: toggles road (evidence: `backend/main.py`)
- FastAPI endpoints → Dispatch coordinator: forwards messages (evidence: `backend/main.py`)
- Dispatch coordinator → District network generator: seeds network (evidence: `backend/state/network_state.py`)
- Dispatch coordinator → Constraint and cost matcher: matches candidates (evidence: `backend/state/network_state.py`)
- Dispatch coordinator → A* / Dijkstra router: routes trips (evidence: `backend/state/network_state.py`)
- Constraint and cost matcher → A* / Dijkstra router: evaluates paths (evidence: `backend/core/matcher.py`)
- Constraint and cost matcher → Road graph: reads network (evidence: `backend/core/matcher.py`)
- A* / Dijkstra router → Road graph: traverses (evidence: `backend/core/router.py`)
- District network generator → Road graph: builds roads (evidence: `backend/core/generator.py`)
- FastAPI endpoints → A* / Dijkstra router: benchmarks paths (evidence: `backend/main.py`)
- Dispatch coordinator → Dispatch audit store: records dispatches (evidence: `README.md`)
- FastAPI endpoints → Dispatch audit store: reads logs (evidence: `backend/main.py`)
- Backend service → FastAPI endpoints: serves requests
- FastAPI endpoints → Network client: streams telemetry (evidence: `README.md`)
- Network client → Dispatch workspace: provides state (evidence: `frontend/src/App.jsx`)
