# shriram28baskar/route-resilience architecture

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

- Interactive diagram: https://gitdiagram.com/shriram28baskar/route-resilience
- Repository: https://github.com/shriram28baskar/route-resilience

## Overview

1. **System shape**
   Route Resilience is a two-tier application: a Python FastAPI backend that performs geospatial ML, graph analysis, and simulation, and a Next.js frontend that presents maps, metrics, scenario controls, and report/copot interactions. The backend is the computational core; the frontend is a thin interactive client.

2. **Primary data flow**
   The main pipeline starts with satellite or map imagery and road-related geodata, passes through road segmentation, then graph construction, then criticality and resilience analysis, and finally feeds simulation outputs into the dashboard, evacuation planner, and PDF report generator. This is the core architecture to draw: imagery → mask → graph → analytics/simulations → UI outputs.

3. **Backend API boundary**
   `backend/app/api/` exposes distinct domain endpoints: segmentation, graph building, simulation, reports, Bhuvan integration, accessibility analytics, and copilot queries. This separation is important because each endpoint maps to a subsystem rather than a generic monolith. The backend’s `main.py` is the FastAPI composition point.

4. **ML and image understanding subsystem**
   `backend/app/ml/` handles the raster-side intelligence: model definition, inference, augmentation-based occlusion robustness, change detection, explainability, and training. This layer turns image tiles into road masks and confidence/explanation artifacts. It is the entry point for the “occlusion-robust road extraction” part of the product.

5. **Graph construction and topology subsystem**
   `backend/app/graph_pipeline/` converts masks into road graphs and repairs topology. The key stages are skeletonization, graph building, centrality analysis, MST-based healing, and metrics extraction. This is where pixel outputs become a network representation that can support junction criticality, connectivity, and partition analysis.

6. **Simulation and resilience subsystem**
   `backend/app/simulation/` contains the scenario engine: cascade failure, ablation, evacuation routing, resilience scoring, equity impact, fragility, traffic impact, temporal degradation, and topography/flood-related effects. These modules consume the graph and its attributes, then produce scenario-specific outputs such as failed nodes, impacted population, route detours, and resilience indices.

7. **External data and mapping integrations**
   `backend/app/integrations/` wraps outside services used by the system: ISRO Bhuvan for map layers and road/context overlays, Overpass and Nominatim for open geodata lookups, and Groq for the AI copilot. These integrations are important architectural boundaries because they augment local computation with live geospatial data and LLM-driven assistance.

8. **Reporting layer**
   `backend/app/reports/generator.py` produces situation reports from the computed analytics and simulations. In the architecture, this is a downstream consumer of all prior subsystems, turning technical outputs into a decision-support artifact suitable for NDMA/operations-style sharing.

9. **Frontend application structure**
   The Next.js app in `frontend/app/` is organized by task: map, analytics, simulate, reports, explain, and copilot pages. Shared UI components such as `RoadMap`, `SplitMapView`, `EvacuationPanel`, and metric cards render the geospatial outputs and scenario controls. The frontend does not perform heavy computation; it orchestrates backend calls and visualization.

10. **Client-server interaction pattern**
   `frontend/lib/api.ts` is the client-side API boundary. UI pages request segmentation results, graphs, simulation outcomes, and reports from the backend, then render them as maps, charts, and scenario panels. This makes the frontend a presentation and interaction layer rather than a data-processing layer.

11. **Persistent assets and offline data**
   `backend/data/graphs/` stores prebuilt graph artifacts, and `backend/cache/` stores cached computation results. The presence of `scripts/download_data.py` and `scripts/rasterize_masks.py` shows that some data preparation happens offline or ahead of runtime, reducing repeated processing during demos or API calls.

12. **Operational packaging**
   The repo is designed for local development and Docker-based deployment. `docker-compose.yml`, backend/frontend Dockerfiles, and the startup scripts imply a reproducible full-stack environment where the frontend and backend run as separate services. The backend is Python 3.11/FastAPI; the frontend is React/Next.js 14 with TypeScript and Leaflet-style mapping.

13. **Validation and experimentation boundary**
   The `notebooks/` directory and `backend/tests/test_analytics.py` indicate an analytical/experimental workflow alongside the product code. Notebooks are for exploration, model evaluation, graph validation, and QA of assumptions; tests cover analytics behavior at least at a unit/integration level.

14. **What to show in an architecture diagram**
   A clear diagram should show: external inputs from satellite tiles, road data, and map services; the backend as a pipeline of ML → graph → simulation → reporting; the frontend as a separate presentation shell; and external services like Bhuvan, Overpass/Nominatim, and Groq connected only through integration modules. The main trust boundary is between the browser UI and the backend API, and the main compute boundary is between geospatial ML/analysis and the interactive dashboard.

Main entry points: [`backend/app/main.py`](https://github.com/shriram28baskar/route-resilience/blob/main/backend/app/main.py) (Main API), [`backend/app/integrations`](https://github.com/shriram28baskar/route-resilience/tree/main/backend/app/integrations) (Integrations), [`frontend/components`](https://github.com/shriram28baskar/route-resilience/tree/main/frontend/components) (UI Shell), [`backend/app/simulation`](https://github.com/shriram28baskar/route-resilience/tree/main/backend/app/simulation) (Simulation Core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_main["Main API<br/>FastAPI app<br/>[main.py]"]
  node_backend_api_segmentation["Segmentation<br/>API route<br/>[segmentation.py]"]
  node_backend_api_graph["Graph API<br/>API route<br/>[graph.py]"]
  node_backend_api_simulation["Simulation API<br/>API route<br/>[simulation.py]"]
  node_backend_api_reports["Reports API<br/>API route<br/>[reports.py]"]
  node_backend_api_accessibility["Accessibility API<br/>API route<br/>[accessibility.py]"]
  node_backend_api_bhuvan["Bhuvan API<br/>API route<br/>[bhuvan.py]"]
  node_backend_api_copilot["Copilot API<br/>API route<br/>[copilot.py]"]
  node_backend_ml{{"Road ML<br/>vision pipeline"}}
  node_backend_graph_pipeline{{"Graph Pipeline<br/>topology pipeline"}}
  node_backend_simulation{{"Simulation Core<br/>scenario engine"}}
  node_backend_reports["Report Generator<br/>reporting<br/>[generator.py]"]
  node_backend_integrations["Integrations<br/>external adapters"]
end

subgraph group_frontend["Frontend"]
  node_frontend_pages["App Pages<br/>Next.js routes"]
  node_frontend_components["UI Shell<br/>React components"]
  node_frontend_api["Client API<br/>browser client<br/>[api.ts]"]
end

subgraph group_external["External"]
  node_external_bhuvan[("Bhuvan<br/>map service")]
  node_external_overpass[("Overpass<br/>open geodata")]
  node_external_nominatim[("Nominatim<br/>geocoder")]
  node_external_groq[("Groq<br/>LLM service")]
end

subgraph group_assets["Assets"]
  node_assets_graphs[("Graph Cache<br/>stored artifacts")]
  node_assets_cache[("Runtime Cache<br/>cached results")]
end

node_frontend_pages -->|"renders"| node_frontend_components
node_frontend_pages -->|"calls"| node_frontend_api
node_frontend_api -->|"HTTP API"| node_backend_main
node_backend_main -->|"mounts"| node_backend_api_segmentation
node_backend_main -->|"mounts"| node_backend_api_graph
node_backend_main -->|"mounts"| node_backend_api_simulation
node_backend_main -->|"mounts"| node_backend_api_reports
node_backend_main -->|"mounts"| node_backend_api_accessibility
node_backend_main -->|"mounts"| node_backend_api_bhuvan
node_backend_main -->|"mounts"| node_backend_api_copilot
node_backend_api_segmentation -->|"runs"| node_backend_ml
node_backend_ml -->|"emits masks"| node_backend_graph_pipeline
node_backend_graph_pipeline -->|"serves graphs"| node_backend_api_graph
node_backend_graph_pipeline -->|"feeds"| node_backend_simulation
node_backend_api_simulation -->|"executes"| node_backend_simulation
node_backend_simulation -->|"produces outputs"| node_backend_reports
node_backend_reports -->|"exposes"| node_backend_api_reports
node_backend_api_bhuvan -->|"adapts"| node_backend_integrations
node_backend_api_copilot -->|"adapts"| node_backend_integrations
node_backend_integrations -->|"uses"| node_external_bhuvan
node_backend_integrations -->|"uses"| node_external_overpass
node_backend_integrations -->|"uses"| node_external_nominatim
node_backend_integrations -->|"uses"| node_external_groq
node_backend_api_graph -->|"reads"| node_assets_graphs
node_backend_ml -->|"reads/writes"| node_assets_cache
node_backend_simulation -->|"reads/writes"| node_assets_cache
node_frontend_components -->|"drives"| node_backend_api_simulation
node_frontend_components -->|"visualizes"| node_backend_api_graph
node_frontend_components -->|"downloads"| node_backend_api_reports

click node_backend_main "https://github.com/shriram28baskar/route-resilience/blob/main/backend/app/main.py"
click node_backend_api_segmentation "https://github.com/shriram28baskar/route-resilience/blob/main/backend/app/api/segmentation.py"
click node_backend_api_graph "https://github.com/shriram28baskar/route-resilience/blob/main/backend/app/api/graph.py"
click node_backend_api_simulation "https://github.com/shriram28baskar/route-resilience/blob/main/backend/app/api/simulation.py"
click node_backend_api_reports "https://github.com/shriram28baskar/route-resilience/blob/main/backend/app/api/reports.py"
click node_backend_api_accessibility "https://github.com/shriram28baskar/route-resilience/blob/main/backend/app/api/accessibility.py"
click node_backend_api_bhuvan "https://github.com/shriram28baskar/route-resilience/blob/main/backend/app/api/bhuvan.py"
click node_backend_api_copilot "https://github.com/shriram28baskar/route-resilience/blob/main/backend/app/api/copilot.py"
click node_backend_ml "https://github.com/shriram28baskar/route-resilience/tree/main/backend/app/ml"
click node_backend_graph_pipeline "https://github.com/shriram28baskar/route-resilience/tree/main/backend/app/graph_pipeline"
click node_backend_simulation "https://github.com/shriram28baskar/route-resilience/tree/main/backend/app/simulation"
click node_backend_reports "https://github.com/shriram28baskar/route-resilience/blob/main/backend/app/reports/generator.py"
click node_backend_integrations "https://github.com/shriram28baskar/route-resilience/tree/main/backend/app/integrations"
click node_frontend_pages "https://github.com/shriram28baskar/route-resilience/tree/main/frontend/app"
click node_frontend_components "https://github.com/shriram28baskar/route-resilience/tree/main/frontend/components"
click node_frontend_api "https://github.com/shriram28baskar/route-resilience/blob/main/frontend/lib/api.ts"
click node_assets_graphs "https://github.com/shriram28baskar/route-resilience/tree/main/backend/data/graphs"
click node_assets_cache "https://github.com/shriram28baskar/route-resilience/tree/main/backend/cache"

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_backend_main,node_backend_api_segmentation,node_backend_api_graph,node_backend_api_simulation,node_backend_api_reports,node_backend_api_accessibility,node_backend_api_bhuvan,node_backend_api_copilot,node_backend_ml,node_backend_graph_pipeline,node_backend_simulation,node_backend_reports,node_backend_integrations toneBlue
class node_frontend_pages,node_frontend_components,node_frontend_api toneAmber
class node_external_bhuvan,node_external_overpass,node_external_nominatim,node_external_groq toneMint
class node_assets_graphs,node_assets_cache toneRose
```

## Components

### Backend

FastAPI geospatial computation and API surface

- [Main API](https://github.com/shriram28baskar/route-resilience/blob/main/backend/app/main.py): FastAPI app · Composes the backend service and mounts domain routes · `backend/app/main.py`
- [Segmentation](https://github.com/shriram28baskar/route-resilience/blob/main/backend/app/api/segmentation.py): API route · Image-to-mask endpoint for road extraction · `backend/app/api/segmentation.py`
- [Graph API](https://github.com/shriram28baskar/route-resilience/blob/main/backend/app/api/graph.py): API route · Endpoints for building and inspecting road graphs · `backend/app/api/graph.py`
- [Simulation API](https://github.com/shriram28baskar/route-resilience/blob/main/backend/app/api/simulation.py): API route · Scenario execution and resilience outputs · `backend/app/api/simulation.py`
- [Reports API](https://github.com/shriram28baskar/route-resilience/blob/main/backend/app/api/reports.py): API route · Report generation and export endpoint · `backend/app/api/reports.py`
- [Accessibility API](https://github.com/shriram28baskar/route-resilience/blob/main/backend/app/api/accessibility.py): API route · Accessibility and reachability analytics endpoint · `backend/app/api/accessibility.py`
- [Bhuvan API](https://github.com/shriram28baskar/route-resilience/blob/main/backend/app/api/bhuvan.py): API route · Geospatial layer and overlay integration endpoint · `backend/app/api/bhuvan.py`
- [Copilot API](https://github.com/shriram28baskar/route-resilience/blob/main/backend/app/api/copilot.py): API route · LLM-assisted query and guidance endpoint · `backend/app/api/copilot.py`
- [Road ML](https://github.com/shriram28baskar/route-resilience/tree/main/backend/app/ml): vision pipeline · Model inference, augmentation, change detection, and explainability · `backend/app/ml`
- [Graph Pipeline](https://github.com/shriram28baskar/route-resilience/tree/main/backend/app/graph_pipeline): topology pipeline · Skeletonizes masks and builds connected road graphs · `backend/app/graph_pipeline`
- [Simulation Core](https://github.com/shriram28baskar/route-resilience/tree/main/backend/app/simulation): scenario engine · Runs failure, evacuation, traffic, and resilience scenarios · `backend/app/simulation`
- [Report Generator](https://github.com/shriram28baskar/route-resilience/blob/main/backend/app/reports/generator.py): reporting · Formats analytics and scenarios into decision reports · `backend/app/reports/generator.py`
- [Integrations](https://github.com/shriram28baskar/route-resilience/tree/main/backend/app/integrations): external adapters · Wrappers for map, geodata, and AI services · `backend/app/integrations`

### Frontend

Next.js presentation and interaction layer

- [App Pages](https://github.com/shriram28baskar/route-resilience/tree/main/frontend/app): Next.js routes · Map, analytics, simulate, reports, explain, and copilot screens · `frontend/app`
- [UI Shell](https://github.com/shriram28baskar/route-resilience/tree/main/frontend/components): React components · Shared map and control components for geospatial interaction · `frontend/components`
- [Client API](https://github.com/shriram28baskar/route-resilience/blob/main/frontend/lib/api.ts): browser client · Typed frontend boundary for backend requests · `frontend/lib/api.ts`

### External

Third-party data and AI services

- **Bhuvan**: map service · Satellite and contextual map layers
- **Overpass**: open geodata · OpenStreetMap-style road and place lookups
- **Nominatim**: geocoder · Address and place geocoding service
- **Groq**: LLM service · AI backend used for copilot responses

### Assets

Precomputed data and cached artifacts

- [Graph Cache](https://github.com/shriram28baskar/route-resilience/tree/main/backend/data/graphs): stored artifacts · Prebuilt graphs and cached computation outputs · `backend/data/graphs`
- [Runtime Cache](https://github.com/shriram28baskar/route-resilience/tree/main/backend/cache): cached results · Serialized API and analysis cache files · `backend/cache`

## Connections

- App Pages → UI Shell: renders · Pages compose shared map and control widgets
- App Pages → Client API: calls · UI requests backend data and scenario results
- Client API → Main API: HTTP API · Client-server boundary into the FastAPI app
- Main API → Segmentation: mounts · Registers segmentation endpoints
- Main API → Graph API: mounts · Registers graph endpoints
- Main API → Simulation API: mounts · Registers simulation endpoints
- Main API → Reports API: mounts · Registers reporting endpoints
- Main API → Accessibility API: mounts · Registers accessibility endpoints
- Main API → Bhuvan API: mounts · Registers Bhuvan integration endpoints
- Main API → Copilot API: mounts · Registers copilot endpoints
- Segmentation → Road ML: runs · Segmentation routes invoke raster ML
- Road ML → Graph Pipeline: emits masks · Model outputs feed topology reconstruction
- Graph Pipeline → Graph API: serves graphs · Graph products are exposed through the API
- Graph Pipeline → Simulation Core: feeds · Topology metrics become scenario inputs
- Simulation API → Simulation Core: executes · Scenario endpoints dispatch the simulation core
- Simulation Core → Report Generator: produces outputs · Scenario results are packaged for reporting
- Report Generator → Reports API: exposes · Report generator is served through the API
- Bhuvan API → Integrations: adapts · Bhuvan-specific wrapper layer
- Copilot API → Integrations: adapts · Copilot endpoint uses integration clients
- Integrations → Bhuvan: uses · Fetches satellite and overlay data
- Integrations → Overpass: uses · Queries open road and place data
- Integrations → Nominatim: uses · Resolves locations and addresses
- Integrations → Groq: uses · Delegates LLM copilot calls
- Graph API → Graph Cache: reads · Graph endpoints can reuse prebuilt artifacts
- Road ML → Runtime Cache: reads/writes · Inference and analysis may persist cached results
- Simulation Core → Runtime Cache: reads/writes · Scenario outputs may be cached for reuse
- UI Shell → Simulation API: drives · Evacuation and scenario controls trigger simulation runs
- UI Shell → Graph API: visualizes · Map views render graph and topology data
- UI Shell → Reports API: downloads · Report views fetch generated documents