shriram28baskar/route-resilience

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.