# soumalyasaha/flood-nowcast architecture

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

- Interactive diagram: https://gitdiagram.com/soumalyasaha/flood-nowcast
- Repository: https://github.com/soumalyasaha/flood-nowcast

## Overview

Flood Risk Nowcast is a Kolkata flood-risk dashboard with a browser map, scenario playback, analytics, incident views, and a live-prediction screen. Users enter through the routed app, select or view a simulation, and inspect changing flood-risk results across modeled areas. The frontend shares simulation state and requests backend endpoints; the backend computes risk for three distinct drainage mechanisms. The map also presents ward boundaries, historical flood zones, pumping stations, and pipeline overlays. Backend data loading and several page-level interactions are not fully shown in the excerpts, so those links are omitted where unverified.

Main entry points: [`frontend/src/App.tsx`](https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/App.tsx) (App Router), [`frontend/src/pages/MapViewPage.tsx`](https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/pages/MapViewPage.tsx) (Risk Map), [`frontend/src/context/SimulationContext.tsx`](https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/context/SimulationContext.tsx) (Simulation State), [`backend/main.py`](https://github.com/soumalyasaha/flood-nowcast/blob/main/backend/main.py) (Nowcast API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dashboard"]
  node_app["App Router<br/>[App.tsx]"]
  node_layout["App Layout<br/>[AppLayout.tsx]"]
  node_map["Risk Map<br/>[MapViewPage.tsx]"]
  node_analytics["Analytics<br/>[AnalyticsPage.tsx]"]
  node_incidents["Incidents<br/>[IncidentsPage.tsx]"]
  node_live["Live Prediction"]
  node_header["Header Bar<br/>[HeaderBar.tsx]"]
  node_legend["Hazard Legend<br/>[Legend.tsx]"]
  node_metrics["Metric Cards<br/>[MetricCard.tsx]"]
  node_clock["Simulation Clock"]
end

subgraph group_simulation["Simulation Client"]
  node_sim_context["Simulation State"]
  node_sim_hook["Simulation Hook<br/>[useSimulation.ts]"]
  node_ward_hook["Ward Data Hook<br/>[useWards.ts]"]
  node_layers_hook["Map Layer State<br/>[useMapLayers.ts]"]
  node_api_client["API Client<br/>[config.ts]"]
end

subgraph group_backend["Risk Backend"]
  node_api_backend["Nowcast API<br/>[main.py]"]
  node_local_data["Scenario Data"]
end

subgraph group_geodata["Map Data"]
  node_ward_shapes["Ward Geometries"]
  node_pipeline["Ward Pipeline<br/>[ward96_pipeline.ts]"]
end

node_user(("Dashboard User"))
node_basemap["Map Tile Service"]

node_user -->|"opens"| node_app
node_app -->|"renders"| node_layout
node_app -->|"routes to"| node_map
node_app -->|"routes to"| node_analytics
node_app -->|"routes to"| node_incidents
node_app -->|"routes to"| node_live
node_app -->|"provides"| node_sim_context
node_map -->|"reads state"| node_sim_hook
node_sim_hook -->|"delegates to"| node_sim_context
node_map -->|"renders"| node_legend
node_map -->|"renders"| node_metrics
node_map -->|"renders"| node_ward_shapes
node_map -->|"uses"| node_pipeline
node_map -->|"requests tiles"| node_basemap
node_sim_context -->|"requests"| node_api_client
node_api_client -->|"calls endpoints"| node_api_backend
node_ward_hook -->|"fetches wards"| node_api_backend
node_sim_context -->|"starts and steps"| node_api_backend
node_sim_context -->|"requests prediction"| node_api_backend
node_api_backend -.->|"loads scenarios"| node_local_data

click node_app "https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/App.tsx"
click node_layout "https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/components/layout/AppLayout.tsx"
click node_map "https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/pages/MapViewPage.tsx"
click node_analytics "https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/pages/AnalyticsPage.tsx"
click node_incidents "https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/pages/IncidentsPage.tsx"
click node_live "https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/pages/LivePredictionPage.tsx"
click node_header "https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/components/ui/HeaderBar.tsx"
click node_legend "https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/components/ui/Legend.tsx"
click node_metrics "https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/components/ui/MetricCard.tsx"
click node_clock "https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/components/ui/SimulationClock.tsx"
click node_sim_context "https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/context/SimulationContext.tsx"
click node_sim_hook "https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/hooks/useSimulation.ts"
click node_ward_hook "https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/hooks/useWards.ts"
click node_layers_hook "https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/hooks/useMapLayers.ts"
click node_api_client "https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/api/config.ts"
click node_api_backend "https://github.com/soumalyasaha/flood-nowcast/blob/main/backend/main.py"
click node_local_data "https://github.com/soumalyasaha/flood-nowcast/tree/main/backend/data"
click node_ward_shapes "https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/data/kolkata_ward_polygons.ts"
click node_pipeline "https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/data/ward96_pipeline.ts"

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_layout,node_map,node_analytics,node_incidents,node_live,node_header,node_legend,node_metrics,node_clock,node_user toneBlue
class node_sim_context,node_sim_hook,node_ward_hook,node_layers_hook,node_api_client toneAmber
class node_api_backend,node_local_data toneMint
class node_ward_shapes,node_pipeline toneRose
class node_basemap toneIndigo
```

## Components

### Dashboard

- [App Router](https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [App Layout](https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/components/layout/AppLayout.tsx): `frontend/src/components/layout/AppLayout.tsx`
- [Risk Map](https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/pages/MapViewPage.tsx): `frontend/src/pages/MapViewPage.tsx`
- [Analytics](https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/pages/AnalyticsPage.tsx): `frontend/src/pages/AnalyticsPage.tsx`
- [Incidents](https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/pages/IncidentsPage.tsx): `frontend/src/pages/IncidentsPage.tsx`
- [Live Prediction](https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/pages/LivePredictionPage.tsx): `frontend/src/pages/LivePredictionPage.tsx`
- [Header Bar](https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/components/ui/HeaderBar.tsx): `frontend/src/components/ui/HeaderBar.tsx`
- [Hazard Legend](https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/components/ui/Legend.tsx): `frontend/src/components/ui/Legend.tsx`
- [Metric Cards](https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/components/ui/MetricCard.tsx): `frontend/src/components/ui/MetricCard.tsx`
- [Simulation Clock](https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/components/ui/SimulationClock.tsx): `frontend/src/components/ui/SimulationClock.tsx`

### Simulation Client

- [Simulation State](https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/context/SimulationContext.tsx): `frontend/src/context/SimulationContext.tsx`
- [Simulation Hook](https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/hooks/useSimulation.ts): `frontend/src/hooks/useSimulation.ts`
- [Ward Data Hook](https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/hooks/useWards.ts): `frontend/src/hooks/useWards.ts`
- [Map Layer State](https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/hooks/useMapLayers.ts): `frontend/src/hooks/useMapLayers.ts`
- [API Client](https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/api/config.ts): `frontend/src/api/config.ts`

### Risk Backend

- [Nowcast API](https://github.com/soumalyasaha/flood-nowcast/blob/main/backend/main.py): `backend/main.py`
- [Scenario Data](https://github.com/soumalyasaha/flood-nowcast/tree/main/backend/data): `backend/data`

### Map Data

- [Ward Geometries](https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/data/kolkata_ward_polygons.ts): `frontend/src/data/kolkata_ward_polygons.ts`
- [Ward Pipeline](https://github.com/soumalyasaha/flood-nowcast/blob/main/frontend/src/data/ward96_pipeline.ts): `frontend/src/data/ward96_pipeline.ts`

### Other components

- **Dashboard User**
- **Map Tile Service**

## Connections

- Dashboard User → App Router: opens
- App Router → App Layout: renders (evidence: `frontend/src/App.tsx`)
- App Router → Risk Map: routes to (evidence: `frontend/src/App.tsx`)
- App Router → Analytics: routes to (evidence: `frontend/src/App.tsx`)
- App Router → Incidents: routes to (evidence: `frontend/src/App.tsx`)
- App Router → Live Prediction: routes to (evidence: `frontend/src/App.tsx`)
- App Router → Simulation State: provides (evidence: `frontend/src/App.tsx`)
- Risk Map → Simulation Hook: reads state (evidence: `frontend/src/pages/MapViewPage.tsx`)
- Simulation Hook → Simulation State: delegates to (evidence: `frontend/src/hooks/useSimulation.ts`)
- Risk Map → Hazard Legend: renders (evidence: `frontend/src/pages/MapViewPage.tsx`)
- Risk Map → Metric Cards: renders (evidence: `frontend/src/pages/MapViewPage.tsx`)
- Risk Map → Ward Geometries: renders (evidence: `frontend/src/pages/MapViewPage.tsx`)
- Risk Map → Ward Pipeline: uses (evidence: `frontend/src/pages/MapViewPage.tsx`)
- Risk Map → Map Tile Service: requests tiles (evidence: `frontend/src/pages/MapViewPage.tsx`)
- Simulation State → API Client: requests (evidence: `frontend/src/context/SimulationContext.tsx`)
- API Client → Nowcast API: calls endpoints
- Ward Data Hook → Nowcast API: fetches wards (evidence: `frontend/src/hooks/useWards.ts`)
- Simulation State → Nowcast API: starts and steps (evidence: `frontend/src/context/SimulationContext.tsx`)
- Simulation State → Nowcast API: requests prediction (evidence: `frontend/src/context/SimulationContext.tsx`)
- Nowcast API → Scenario Data: loads scenarios