# harit117/road_routing_geoagentic_solution architecture

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

- Interactive diagram: https://gitdiagram.com/harit117/road_routing_geoagentic_solution
- Repository: https://github.com/harit117/road_routing_geoagentic_solution

## Overview

This is a FastAPI flood-aware emergency-routing service with a map interface. A user can inspect the road network and flood context, run or select rainfall simulations, view road-risk states, and request emergency routes that account for flooding. The runtime has two related flood-modeling paths: a normalized scenario risk engine and a time-stepped simulation with registered flood models; routing can use forecast loading to find safer facility routes. The README is empty, so capabilities and links here rely on the supplied source index and excerpts; unsampled details are omitted where their relationships are not evidenced.

Main entry points: [`backend/app/flood/risk_engine.py`](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/flood/risk_engine.py) (Risk engine), [`backend/app/main.py`](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/main.py) (FastAPI entry), [`backend/app/simulation/flood_models/susceptibility_bucket.py`](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/simulation/flood_models/susceptibility_bucket.py) (Susceptibility model), [`backend/app/routing/planner.py`](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/routing/planner.py) (Mission planner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application API"]
  node_map["Map interface<br/>[app.js]"]
  node_entry["FastAPI entry<br/>[main.py]"]
  node_network_api["Network API<br/>[network.py]"]
  node_simulation_api["Simulation API<br/>[simulation.py]"]
  node_risk_api["Flood-risk API<br/>[flood_risk.py]"]
  node_routing_api["Routing API<br/>[routing.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
end

subgraph group_network["Road network"]
  node_network_loader["Network loader<br/>[loader.py]"]
  node_network_model["Road network model<br/>[models.py]"]
end

subgraph group_flood["Flood risk"]
  node_risk_engine["Risk engine<br/>[risk_engine.py]"]
  node_risk_config["Risk parameters<br/>[config.py]"]
  node_risk_models["Risk data types<br/>[models.py]"]
  node_susceptibility["Susceptibility scoring<br/>[susceptibility.py]"]
  node_bucket_model["Bucket model<br/>[bucket_model.py]"]
  node_rainfall_provider["Scenario rainfall"]
end

subgraph group_simulation["Simulation"]
  node_risk_service["Risk service adapter"]
  node_sim_engine["Time-step engine<br/>[engine.py]"]
  node_sim_rainfall["Rainfall series<br/>[rainfall.py]"]
  node_model_contract["Flood model contract<br/>[base.py]"]
  node_susceptibility_model["Susceptibility model"]
  node_placeholder_model["Placeholder model"]
  node_model_registry["Model registry<br/>[__init__.py]"]
end

subgraph group_routing["Emergency routing"]
  node_risk_forecast["Flood forecast<br/>[forecast.py]"]
  node_routing_graph["Routing graph<br/>[graph.py]"]
  node_geo["Geospatial helpers<br/>[geo.py]"]
  node_planner["Mission planner<br/>[planner.py]"]
  node_astar["A-star search<br/>[astar.py]"]
  node_facilities["Emergency facilities<br/>[facilities.py]"]
  node_missions["Mission profiles<br/>[missions.py]"]
end

node_user(("Map user"))

node_user -->|"uses"| node_map
node_entry -->|"registers"| node_network_api
node_entry -->|"registers"| node_simulation_api
node_entry -->|"registers"| node_risk_api
node_entry -->|"registers"| node_routing_api
node_entry -->|"loads"| node_network_loader
node_entry -->|"initializes"| node_planner
node_entry -->|"initializes"| node_risk_engine
node_entry -->|"builds demo"| node_simulation_api
node_network_loader -->|"builds"| node_network_model
node_network_api -->|"uses"| node_network_model
node_risk_engine -->|"reads roads"| node_network_model
node_risk_engine -->|"uses"| node_risk_config
node_risk_engine -->|"uses"| node_risk_models
node_risk_engine -->|"scores"| node_susceptibility
node_risk_engine -->|"advances"| node_bucket_model
node_risk_engine -->|"loads scenarios"| node_rainfall_provider
node_rainfall_provider -->|"uses presets"| node_sim_rainfall
node_risk_api -->|"calls"| node_risk_service
node_risk_api -->|"uses"| node_risk_engine
node_risk_api -->|"uses"| node_schemas
node_risk_service -->|"runs scenarios"| node_risk_engine
node_risk_service -->|"reads active simulation"| node_sim_engine
node_risk_service -->|"returns states"| node_schemas
node_simulation_api -->|"builds and runs"| node_sim_engine
node_simulation_api -->|"uses"| node_sim_rainfall
node_simulation_api -->|"selects model"| node_model_registry
node_simulation_api -->|"uses"| node_schemas
node_sim_engine -->|"simulates network"| node_network_model
node_sim_engine -->|"steps model"| node_model_contract
node_sim_engine -->|"consumes series"| node_sim_rainfall
node_model_registry -->|"registers"| node_model_contract
node_model_registry -->|"registers"| node_susceptibility_model
node_model_registry -->|"registers"| node_placeholder_model
node_susceptibility_model -->|"implements"| node_model_contract
node_susceptibility_model -->|"uses"| node_risk_config
node_susceptibility_model -->|"uses"| node_risk_models
node_susceptibility_model -->|"calculates"| node_susceptibility
node_susceptibility_model -->|"advances"| node_bucket_model
node_susceptibility_model -->|"reads roads"| node_network_model
node_routing_api -->|"plans routes"| node_planner
node_routing_api -->|"builds forecast"| node_risk_forecast
node_planner -->|"reads loading"| node_risk_forecast
node_planner -->|"searches graph"| node_routing_graph
node_planner -->|"calls"| node_astar
node_planner -->|"chooses destination"| node_facilities
node_planner -->|"uses profile"| node_missions
node_routing_graph -->|"builds routing view"| node_network_model

click node_map "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/static/app.js"
click node_entry "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/main.py"
click node_network_api "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/api/network.py"
click node_simulation_api "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/api/simulation.py"
click node_risk_api "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/api/flood_risk.py"
click node_routing_api "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/api/routing.py"
click node_schemas "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/api/schemas.py"
click node_network_loader "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/network/loader.py"
click node_network_model "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/network/models.py"
click node_risk_engine "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/flood/risk_engine.py"
click node_risk_config "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/flood/config.py"
click node_risk_models "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/flood/models.py"
click node_susceptibility "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/flood/susceptibility.py"
click node_bucket_model "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/flood/bucket_model.py"
click node_rainfall_provider "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/flood/rainfall_provider.py"
click node_risk_service "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/simulation/flood_risk_service.py"
click node_sim_engine "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/simulation/engine.py"
click node_sim_rainfall "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/simulation/rainfall.py"
click node_model_contract "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/simulation/flood_models/base.py"
click node_susceptibility_model "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/simulation/flood_models/susceptibility_bucket.py"
click node_placeholder_model "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/simulation/flood_models/placeholder_bucket.py"
click node_model_registry "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/simulation/flood_models/__init__.py"
click node_risk_forecast "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/routing/forecast.py"
click node_routing_graph "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/routing/graph.py"
click node_geo "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/routing/geo.py"
click node_planner "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/routing/planner.py"
click node_astar "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/routing/astar.py"
click node_facilities "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/routing/facilities.py"
click node_missions "https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/routing/missions.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_map,node_entry,node_network_api,node_simulation_api,node_risk_api,node_routing_api,node_schemas,node_user toneBlue
class node_network_loader,node_network_model toneAmber
class node_risk_engine,node_risk_config,node_risk_models,node_susceptibility,node_bucket_model,node_rainfall_provider toneMint
class node_risk_service,node_sim_engine,node_sim_rainfall,node_model_contract,node_susceptibility_model,node_placeholder_model,node_model_registry toneRose
class node_risk_forecast,node_routing_graph,node_geo,node_planner,node_astar,node_facilities,node_missions toneIndigo
```

## Components

### Application API

- [Map interface](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/static/app.js): `backend/static/app.js`
- [FastAPI entry](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/main.py): `backend/app/main.py`
- [Network API](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/api/network.py): `backend/app/api/network.py`
- [Simulation API](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/api/simulation.py): `backend/app/api/simulation.py`
- [Flood-risk API](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/api/flood_risk.py): `backend/app/api/flood_risk.py`
- [Routing API](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/api/routing.py): `backend/app/api/routing.py`
- [API schemas](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/api/schemas.py): `backend/app/api/schemas.py`

### Road network

- [Network loader](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/network/loader.py): `backend/app/network/loader.py`
- [Road network model](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/network/models.py): `backend/app/network/models.py`

### Flood risk

- [Risk engine](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/flood/risk_engine.py): `backend/app/flood/risk_engine.py`
- [Risk parameters](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/flood/config.py): `backend/app/flood/config.py`
- [Risk data types](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/flood/models.py): `backend/app/flood/models.py`
- [Susceptibility scoring](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/flood/susceptibility.py): `backend/app/flood/susceptibility.py`
- [Bucket model](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/flood/bucket_model.py): `backend/app/flood/bucket_model.py`
- [Scenario rainfall](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/flood/rainfall_provider.py): `backend/app/flood/rainfall_provider.py`

### Simulation

- [Risk service adapter](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/simulation/flood_risk_service.py): `backend/app/simulation/flood_risk_service.py`
- [Time-step engine](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/simulation/engine.py): `backend/app/simulation/engine.py`
- [Rainfall series](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/simulation/rainfall.py): `backend/app/simulation/rainfall.py`
- [Flood model contract](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/simulation/flood_models/base.py): `backend/app/simulation/flood_models/base.py`
- [Susceptibility model](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/simulation/flood_models/susceptibility_bucket.py): `backend/app/simulation/flood_models/susceptibility_bucket.py`
- [Placeholder model](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/simulation/flood_models/placeholder_bucket.py): `backend/app/simulation/flood_models/placeholder_bucket.py`
- [Model registry](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/simulation/flood_models/__init__.py): `backend/app/simulation/flood_models/__init__.py`

### Emergency routing

- [Flood forecast](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/routing/forecast.py): `backend/app/routing/forecast.py`
- [Routing graph](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/routing/graph.py): `backend/app/routing/graph.py`
- [Geospatial helpers](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/routing/geo.py): `backend/app/routing/geo.py`
- [Mission planner](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/routing/planner.py): `backend/app/routing/planner.py`
- [A-star search](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/routing/astar.py): `backend/app/routing/astar.py`
- [Emergency facilities](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/routing/facilities.py): `backend/app/routing/facilities.py`
- [Mission profiles](https://github.com/harit117/road_routing_geoagentic_solution/blob/main/backend/app/routing/missions.py): `backend/app/routing/missions.py`

### Other components

- **Map user**

## Connections

- Map user → Map interface: uses
- FastAPI entry → Network API: registers (evidence: `backend/app/main.py`)
- FastAPI entry → Simulation API: registers (evidence: `backend/app/main.py`)
- FastAPI entry → Flood-risk API: registers (evidence: `backend/app/main.py`)
- FastAPI entry → Routing API: registers (evidence: `backend/app/main.py`)
- FastAPI entry → Network loader: loads (evidence: `backend/app/main.py`)
- FastAPI entry → Mission planner: initializes (evidence: `backend/app/main.py`)
- FastAPI entry → Risk engine: initializes (evidence: `backend/app/main.py`)
- FastAPI entry → Simulation API: builds demo (evidence: `backend/app/main.py`)
- Network loader → Road network model: builds (evidence: `backend/app/network/loader.py`)
- Network API → Road network model: uses (evidence: `backend/app/api/network.py`)
- Risk engine → Road network model: reads roads (evidence: `backend/app/flood/risk_engine.py`)
- Risk engine → Risk parameters: uses (evidence: `backend/app/flood/risk_engine.py`)
- Risk engine → Risk data types: uses (evidence: `backend/app/flood/risk_engine.py`)
- Risk engine → Susceptibility scoring: scores (evidence: `backend/app/flood/risk_engine.py`)
- Risk engine → Bucket model: advances (evidence: `backend/app/flood/risk_engine.py`)
- Risk engine → Scenario rainfall: loads scenarios (evidence: `backend/app/flood/risk_engine.py`)
- Scenario rainfall → Rainfall series: uses presets (evidence: `backend/app/flood/rainfall_provider.py`)
- Flood-risk API → Risk service adapter: calls (evidence: `backend/app/api/flood_risk.py`)
- Flood-risk API → Risk engine: uses (evidence: `backend/app/api/flood_risk.py`)
- Flood-risk API → API schemas: uses (evidence: `backend/app/api/flood_risk.py`)
- Risk service adapter → Risk engine: runs scenarios (evidence: `backend/app/simulation/flood_risk_service.py`)
- Risk service adapter → Time-step engine: reads active simulation (evidence: `backend/app/simulation/flood_risk_service.py`)
- Risk service adapter → API schemas: returns states (evidence: `backend/app/simulation/flood_risk_service.py`)
- Simulation API → Time-step engine: builds and runs (evidence: `backend/app/api/simulation.py`)
- Simulation API → Rainfall series: uses (evidence: `backend/app/api/simulation.py`)
- Simulation API → Model registry: selects model (evidence: `backend/app/api/simulation.py`)
- Simulation API → API schemas: uses (evidence: `backend/app/api/simulation.py`)
- Time-step engine → Road network model: simulates network (evidence: `backend/app/simulation/engine.py`)
- Time-step engine → Flood model contract: steps model (evidence: `backend/app/simulation/engine.py`)
- Time-step engine → Rainfall series: consumes series (evidence: `backend/app/simulation/engine.py`)
- Model registry → Flood model contract: registers (evidence: `backend/app/simulation/flood_models/__init__.py`)
- Model registry → Susceptibility model: registers (evidence: `backend/app/simulation/flood_models/__init__.py`)
- Model registry → Placeholder model: registers (evidence: `backend/app/simulation/flood_models/__init__.py`)
- Susceptibility model → Flood model contract: implements (evidence: `backend/app/simulation/flood_models/susceptibility_bucket.py`)
- Susceptibility model → Risk parameters: uses (evidence: `backend/app/simulation/flood_models/susceptibility_bucket.py`)
- Susceptibility model → Risk data types: uses (evidence: `backend/app/simulation/flood_models/susceptibility_bucket.py`)
- Susceptibility model → Susceptibility scoring: calculates (evidence: `backend/app/simulation/flood_models/susceptibility_bucket.py`)
- Susceptibility model → Bucket model: advances (evidence: `backend/app/simulation/flood_models/susceptibility_bucket.py`)
- Susceptibility model → Road network model: reads roads (evidence: `backend/app/simulation/flood_models/susceptibility_bucket.py`)
- Routing API → Mission planner: plans routes (evidence: `backend/app/api/routing.py`)
- Routing API → Flood forecast: builds forecast (evidence: `backend/app/api/routing.py`)
- Mission planner → Flood forecast: reads loading (evidence: `backend/app/routing/planner.py`)
- Mission planner → Routing graph: searches graph (evidence: `backend/app/routing/planner.py`)
- Mission planner → A-star search: calls (evidence: `backend/app/routing/planner.py`)
- Mission planner → Emergency facilities: chooses destination (evidence: `backend/app/routing/planner.py`)
- Mission planner → Mission profiles: uses profile (evidence: `backend/app/routing/planner.py`)
- Routing graph → Road network model: builds routing view (evidence: `backend/app/routing/graph.py`)
