# paarthexe/routeshield architecture

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

- Interactive diagram: https://gitdiagram.com/paarthexe/routeshield
- Repository: https://github.com/paarthexe/routeshield

## Overview

RouteShield turns an origin/destination and hazard scenario into inspectable evacuation corridors, selecting a viable primary or contingency and checking backup independence. The documented flow covers route discovery, evidence collection, bottleneck and cutoff analysis, viability decisions, and a decision briefing; the React interface presents maps, route comparisons, and operational panels. Source excerpts show the principal API, routing, sampling, and scoring handoffs. Several documented capabilities are represented at their exact service or component paths, but their internal calls are not inferred where source was not sampled.

Main entry points: [`backend/app/api/routes.py`](https://github.com/paarthexe/routeshield/blob/main/backend/app/api/routes.py) (Route API), [`backend/app/services/sampling.py`](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/sampling.py) (Route sampling), [`backend/app/services/agent_service.py`](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/agent_service.py) (Decision pipeline), [`frontend/src/App.jsx`](https://github.com/paarthexe/routeshield/blob/main/frontend/src/App.jsx) (Application shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Route planning UI"]
  node_app["Application shell<br/>[App.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_map["Map and samples<br/>[MapView.jsx]"]
  node_search["Search panel<br/>[SearchPanel.jsx]"]
  node_sidepanel["Decision panels<br/>[SidePanel.jsx]"]
  node_segment_ui["Segment manager<br/>[SegmentManager.jsx]"]
end

subgraph group_api["API orchestration"]
  node_routes_api["Route API<br/>[routes.py]"]
  node_location_api["Location API<br/>[location.py]"]
  node_zone_api["Zone API<br/>[zone.py]"]
end

subgraph group_analysis["Corridor analysis"]
  node_routing["Route discovery<br/>[routing.py]"]
  node_sampling["Route sampling<br/>[sampling.py]"]
  node_agent["Decision pipeline<br/>[agent_service.py]"]
  node_bottleneck["Bottleneck scoring"]
  node_viability["Viability ranking"]
  node_redundancy["Backup independence"]
  node_segmentation["Corridor segments"]
  node_repair["Segment repair"]
  node_isochrone["Hazard cutoff"]
end

subgraph group_evidence["Evidence services"]
  node_geocoding["Geocoding<br/>[geocoding.py]"]
  node_mireye["Mireye hazards<br/>[mireye_service.py]"]
  node_nbi[("Bridge inventory<br/>[nbi_service.py]")]
  node_weather["Weather evidence<br/>[weather_service.py]"]
  node_population["Population exposure"]
  node_capacity["Network capacity"]
  node_incident["Emergency incidents"]
  node_poi["Corridor facilities<br/>[poi_service.py]"]
  node_connectivity["Connectivity gaps"]
  node_traffic["Traffic conditions<br/>[traffic_service.py]"]
  node_scraper["Live web alerts<br/>[scraper_service.py]"]
end

subgraph group_operations["Operational features"]
  node_monitoring["Live monitoring"]
  node_aar["After-action cases<br/>[aar_service.py]"]
  node_zones["Zone allocation<br/>[zone_service.py]"]
  node_cache[("Response cache<br/>[cache.py]")]
end

node_planner(("Planner"))

node_planner -->|"plans evacuation"| node_app
node_app -->|"requests analysis"| node_api_client
node_app -->|"renders map"| node_map
node_app -->|"renders search"| node_search
node_app -->|"renders decisions"| node_sidepanel
node_api_client -->|"posts analysis"| node_routes_api
node_api_client -->|"resolves place"| node_location_api
node_api_client -->|"plans zones"| node_zone_api
node_sidepanel -->|"renders segments"| node_segment_ui
node_segment_ui -->|"requests repair"| node_api_client
node_routes_api -->|"generates routes"| node_routing
node_routes_api -->|"resolves origin"| node_geocoding
node_routes_api -->|"registers routes"| node_monitoring
node_routes_api -->|"fetches alerts"| node_scraper
node_location_api -->|"resolves query"| node_geocoding
node_zone_api -->|"plans evacuation"| node_zones
node_routing -->|"samples corridors"| node_sampling
node_routing -->|"builds segments"| node_segmentation
node_sampling -->|"looks up bridges"| node_nbi
node_sampling -->|"probes hazards"| node_mireye
node_sampling -->|"collects traffic"| node_traffic
node_sampling -->|"collects elevation"| node_weather
node_agent -->|"scores risks"| node_bottleneck
node_agent -->|"ranks corridors"| node_viability
node_agent -->|"checks backup"| node_redundancy
node_agent -->|"asks hazard insight"| node_mireye
node_agent -->|"reports bridge source"| node_nbi
node_routes_api -->|"analyzes exposure"| node_population
node_routes_api -->|"analyzes capacity"| node_capacity
node_routes_api -->|"collects incidents"| node_incident
node_routes_api -->|"collects facilities"| node_poi
node_routes_api -->|"checks dead zones"| node_connectivity
node_routes_api -->|"builds case studies"| node_aar
node_routes_api -->|"computes cutoff"| node_isochrone
node_routes_api -->|"repairs segments"| node_repair
node_routes_api -->|"streams updates"| node_monitoring
node_sampling -.->|"uses cache"| node_cache
node_mireye -.->|"uses cache"| node_cache
node_aar -.->|"uses cache"| node_cache

click node_app "https://github.com/paarthexe/routeshield/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/paarthexe/routeshield/blob/main/frontend/src/services/api.js"
click node_map "https://github.com/paarthexe/routeshield/blob/main/frontend/src/components/MapView.jsx"
click node_search "https://github.com/paarthexe/routeshield/blob/main/frontend/src/components/SearchPanel.jsx"
click node_sidepanel "https://github.com/paarthexe/routeshield/blob/main/frontend/src/components/SidePanel.jsx"
click node_segment_ui "https://github.com/paarthexe/routeshield/blob/main/frontend/src/components/SegmentManager.jsx"
click node_routes_api "https://github.com/paarthexe/routeshield/blob/main/backend/app/api/routes.py"
click node_location_api "https://github.com/paarthexe/routeshield/blob/main/backend/app/api/location.py"
click node_zone_api "https://github.com/paarthexe/routeshield/blob/main/backend/app/api/zone.py"
click node_routing "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/routing.py"
click node_sampling "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/sampling.py"
click node_agent "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/agent_service.py"
click node_bottleneck "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/bottleneck_service.py"
click node_viability "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/viability_service.py"
click node_redundancy "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/redundancy_service.py"
click node_segmentation "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/segmentation_service.py"
click node_repair "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/segment_repair_service.py"
click node_isochrone "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/isochrone_service.py"
click node_geocoding "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/geocoding.py"
click node_mireye "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/mireye_service.py"
click node_nbi "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/nbi_service.py"
click node_weather "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/weather_service.py"
click node_population "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/population_service.py"
click node_capacity "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/capacity_service.py"
click node_incident "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/incident_service.py"
click node_poi "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/poi_service.py"
click node_connectivity "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/connectivity_service.py"
click node_traffic "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/traffic_service.py"
click node_scraper "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/scraper_service.py"
click node_monitoring "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/monitoring_service.py"
click node_aar "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/aar_service.py"
click node_zones "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/zone_service.py"
click node_cache "https://github.com/paarthexe/routeshield/blob/main/backend/app/services/cache.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_api_client,node_map,node_search,node_sidepanel,node_segment_ui toneBlue
class node_routes_api,node_location_api,node_zone_api toneAmber
class node_routing,node_sampling,node_agent,node_bottleneck,node_viability,node_redundancy,node_segmentation,node_repair,node_isochrone toneMint
class node_geocoding,node_mireye,node_nbi,node_weather,node_population,node_capacity,node_incident,node_poi,node_connectivity,node_traffic,node_scraper toneRose
class node_monitoring,node_aar,node_zones,node_cache,node_planner toneIndigo
```

## Components

### Route planning UI

- [Application shell](https://github.com/paarthexe/routeshield/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/paarthexe/routeshield/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Map and samples](https://github.com/paarthexe/routeshield/blob/main/frontend/src/components/MapView.jsx): `frontend/src/components/MapView.jsx`
- [Search panel](https://github.com/paarthexe/routeshield/blob/main/frontend/src/components/SearchPanel.jsx): `frontend/src/components/SearchPanel.jsx`
- [Decision panels](https://github.com/paarthexe/routeshield/blob/main/frontend/src/components/SidePanel.jsx): `frontend/src/components/SidePanel.jsx`
- [Segment manager](https://github.com/paarthexe/routeshield/blob/main/frontend/src/components/SegmentManager.jsx): `frontend/src/components/SegmentManager.jsx`

### API orchestration

- [Route API](https://github.com/paarthexe/routeshield/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`
- [Location API](https://github.com/paarthexe/routeshield/blob/main/backend/app/api/location.py): `backend/app/api/location.py`
- [Zone API](https://github.com/paarthexe/routeshield/blob/main/backend/app/api/zone.py): `backend/app/api/zone.py`

### Corridor analysis

- [Route discovery](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/routing.py): `backend/app/services/routing.py`
- [Route sampling](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/sampling.py): `backend/app/services/sampling.py`
- [Decision pipeline](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/agent_service.py): `backend/app/services/agent_service.py`
- [Bottleneck scoring](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/bottleneck_service.py): `backend/app/services/bottleneck_service.py`
- [Viability ranking](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/viability_service.py): `backend/app/services/viability_service.py`
- [Backup independence](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/redundancy_service.py): `backend/app/services/redundancy_service.py`
- [Corridor segments](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/segmentation_service.py): `backend/app/services/segmentation_service.py`
- [Segment repair](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/segment_repair_service.py): `backend/app/services/segment_repair_service.py`
- [Hazard cutoff](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/isochrone_service.py): `backend/app/services/isochrone_service.py`

### Evidence services

- [Geocoding](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/geocoding.py): `backend/app/services/geocoding.py`
- [Mireye hazards](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/mireye_service.py): `backend/app/services/mireye_service.py`
- [Bridge inventory](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/nbi_service.py): `backend/app/services/nbi_service.py`
- [Weather evidence](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/weather_service.py): `backend/app/services/weather_service.py`
- [Population exposure](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/population_service.py): `backend/app/services/population_service.py`
- [Network capacity](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/capacity_service.py): `backend/app/services/capacity_service.py`
- [Emergency incidents](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/incident_service.py): `backend/app/services/incident_service.py`
- [Corridor facilities](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/poi_service.py): `backend/app/services/poi_service.py`
- [Connectivity gaps](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/connectivity_service.py): `backend/app/services/connectivity_service.py`
- [Traffic conditions](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/traffic_service.py): `backend/app/services/traffic_service.py`
- [Live web alerts](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/scraper_service.py): `backend/app/services/scraper_service.py`

### Operational features

- [Live monitoring](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/monitoring_service.py): `backend/app/services/monitoring_service.py`
- [After-action cases](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/aar_service.py): `backend/app/services/aar_service.py`
- [Zone allocation](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/zone_service.py): `backend/app/services/zone_service.py`
- [Response cache](https://github.com/paarthexe/routeshield/blob/main/backend/app/services/cache.py): `backend/app/services/cache.py`

### Other components

- **Planner**

## Connections

- Planner → Application shell: plans evacuation (evidence: `README.md`)
- Application shell → API client: requests analysis (evidence: `frontend/src/App.jsx`)
- Application shell → Map and samples: renders map (evidence: `frontend/src/App.jsx`)
- Application shell → Search panel: renders search (evidence: `frontend/src/App.jsx`)
- Application shell → Decision panels: renders decisions (evidence: `frontend/src/App.jsx`)
- API client → Route API: posts analysis (evidence: `frontend/src/services/api.js`)
- API client → Location API: resolves place (evidence: `frontend/src/services/api.js`)
- API client → Zone API: plans zones (evidence: `frontend/src/services/api.js`)
- Decision panels → Segment manager: renders segments (evidence: `frontend/src/components/SidePanel.jsx`)
- Segment manager → API client: requests repair (evidence: `frontend/src/components/SegmentManager.jsx`)
- Route API → Route discovery: generates routes (evidence: `backend/app/api/routes.py`)
- Route API → Geocoding: resolves origin (evidence: `backend/app/api/routes.py`)
- Route API → Live monitoring: registers routes (evidence: `backend/app/api/routes.py`)
- Route API → Live web alerts: fetches alerts (evidence: `backend/app/api/routes.py`)
- Location API → Geocoding: resolves query (evidence: `backend/app/api/location.py`)
- Zone API → Zone allocation: plans evacuation (evidence: `backend/app/api/zone.py`)
- Route discovery → Route sampling: samples corridors (evidence: `backend/app/services/routing.py`)
- Route discovery → Corridor segments: builds segments (evidence: `backend/app/services/routing.py`)
- Route sampling → Bridge inventory: looks up bridges (evidence: `backend/app/services/sampling.py`)
- Route sampling → Mireye hazards: probes hazards (evidence: `backend/app/services/sampling.py`)
- Route sampling → Traffic conditions: collects traffic (evidence: `backend/app/services/sampling.py`)
- Route sampling → Weather evidence: collects elevation (evidence: `README.md`)
- Decision pipeline → Bottleneck scoring: scores risks (evidence: `backend/app/services/agent_service.py`)
- Decision pipeline → Viability ranking: ranks corridors (evidence: `backend/app/services/agent_service.py`)
- Decision pipeline → Backup independence: checks backup (evidence: `backend/app/services/agent_service.py`)
- Decision pipeline → Mireye hazards: asks hazard insight (evidence: `backend/app/services/agent_service.py`)
- Decision pipeline → Bridge inventory: reports bridge source (evidence: `backend/app/services/agent_service.py`)
- Route API → Population exposure: analyzes exposure (evidence: `backend/app/api/routes.py`)
- Route API → Network capacity: analyzes capacity (evidence: `backend/app/api/routes.py`)
- Route API → Emergency incidents: collects incidents (evidence: `backend/app/api/routes.py`)
- Route API → Corridor facilities: collects facilities (evidence: `backend/app/api/routes.py`)
- Route API → Connectivity gaps: checks dead zones (evidence: `backend/app/api/routes.py`)
- Route API → After-action cases: builds case studies (evidence: `backend/app/api/routes.py`)
- Route API → Hazard cutoff: computes cutoff (evidence: `backend/app/api/routes.py`)
- Route API → Segment repair: repairs segments (evidence: `backend/app/api/routes.py`)
- Route API → Live monitoring: streams updates (evidence: `backend/app/api/routes.py`)
- Route sampling → Response cache: uses cache
- Mireye hazards → Response cache: uses cache (evidence: `backend/app/services/mireye_service.py`)
- After-action cases → Response cache: uses cache (evidence: `backend/app/services/aar_service.py`)