# iadityachourasia/varshasetu architecture

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

- Interactive diagram: https://gitdiagram.com/iadityachourasia/varshasetu
- Repository: https://github.com/iadityachourasia/varshasetu

## Overview

VarshaSetu is a historical research prototype for regime-aware correction and verification of monsoon rainfall forecasts, presented through a read-only web app and API. Its documented scientific workflow goes from archived GEFS forecasts through forecast-time features and regime-aware correction to rainfall and district products, then verification against IMD observations. The app also exposes frozen evidence, regime analysis, heavy-rain products, and an experimental live-cycle view. Relationships among unsampled subsystems are included only where the README documents them; the live path is explicitly experimental, not an operational warning service.

Main entry points: [`backend/app/api`](https://github.com/iadityachourasia/varshasetu/tree/master/backend/app/api) (API routers), [`backend/app/ml/phase2b.py`](https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/ml/phase2b.py) (Regime-aware correction), [`frontend-v2/src/app`](https://github.com/iadityachourasia/varshasetu/tree/master/frontend-v2/src/app) (Science dashboard), [`backend/app/api/evidence.py`](https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/api/evidence.py) (Evidence endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Web presentation"]
  node_webapp["Science dashboard"]
  node_api_client["API clients"]
end

subgraph group_api["Read-only API"]
  node_api_server["FastAPI service<br/>[main.py]"]
  node_api_routes["API routers"]
  node_operational_api["Operational products<br/>[operational.py]"]
  node_evidence_api["Evidence endpoints<br/>[evidence.py]"]
  node_science_api["Science endpoints<br/>[science.py]"]
  node_regime_api["Regime endpoints"]
  node_coastal_api["Coastal regimes<br/>[coastal_regime.py]"]
  node_geo_api["Geo-aware products<br/>[geoaware.py]"]
  node_zone_api["Zone products<br/>[zones.py]"]
  node_heavy_api["Heavy-rain products<br/>[heavy_rain.py]"]
  node_live_api["Live-cycle endpoint<br/>[live.py]"]
end

subgraph group_science["Forecast science"]
  node_forecast_models["Regime-aware correction<br/>[phase2b.py]"]
  node_district_products["District products"]
  node_heavy_models["Heavy-rain models"]
  node_live_pipeline["Live inference pipeline<br/>[pipeline.py]"]
end

subgraph group_evidence["Data and verification"]
  node_gefs_source[("NOAA GEFS archive<br/>[noaa_gefs.py]")]
  node_imd_source[("IMD rainfall archive<br/>[imd_rainfall.py]")]
  node_frozen_evidence["Frozen evidence<br/>[evidence.py]"]
  node_verification["Verification metrics<br/>[metrics.py]"]
end

node_user(("Research user"))
node_noaa_service[("NOAA GEFS source")]

node_user -->|"explores results"| node_webapp
node_webapp -->|"requests products"| node_api_client
node_api_server -->|"mounts routers"| node_api_routes
node_api_routes -->|"routes requests"| node_operational_api
node_api_routes -->|"routes requests"| node_evidence_api
node_api_routes -->|"routes requests"| node_science_api
node_api_routes -->|"routes requests"| node_regime_api
node_api_routes -->|"routes requests"| node_coastal_api
node_api_routes -->|"routes requests"| node_geo_api
node_api_routes -->|"routes requests"| node_zone_api
node_api_routes -->|"routes requests"| node_heavy_api
node_api_routes -->|"routes requests"| node_live_api
node_gefs_source -->|"provides forecasts"| node_forecast_models
node_forecast_models -->|"produces district grids"| node_district_products
node_forecast_models -->|"estimates extremes"| node_heavy_models
node_imd_source -->|"reference observations"| node_verification
node_forecast_models -->|"evaluated by"| node_verification
node_evidence_api -->|"verifies and serves"| node_frozen_evidence
node_live_api -->|"runs inference"| node_live_pipeline
node_live_pipeline -->|"fetches forecast data"| node_noaa_service

click node_webapp "https://github.com/iadityachourasia/varshasetu/tree/master/frontend-v2/src/app"
click node_api_client "https://github.com/iadityachourasia/varshasetu/tree/master/frontend-v2/src/lib/api"
click node_api_server "https://github.com/iadityachourasia/varshasetu/blob/master/backend/main.py"
click node_api_routes "https://github.com/iadityachourasia/varshasetu/tree/master/backend/app/api"
click node_operational_api "https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/api/operational.py"
click node_evidence_api "https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/api/evidence.py"
click node_science_api "https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/api/science.py"
click node_regime_api "https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/api/regime_validation.py"
click node_coastal_api "https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/api/coastal_regime.py"
click node_geo_api "https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/api/geoaware.py"
click node_zone_api "https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/api/zones.py"
click node_heavy_api "https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/api/heavy_rain.py"
click node_live_api "https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/api/live.py"
click node_forecast_models "https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/ml/phase2b.py"
click node_district_products "https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/ml/district_product.py"
click node_heavy_models "https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/ml/heavy_rain_product.py"
click node_live_pipeline "https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/live/pipeline.py"
click node_gefs_source "https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/data_sources/noaa_gefs.py"
click node_imd_source "https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/data_sources/imd_rainfall.py"
click node_frozen_evidence "https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/api/evidence.py"
click node_verification "https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/verification/metrics.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_webapp,node_api_client,node_user toneBlue
class node_api_server,node_api_routes,node_operational_api,node_evidence_api,node_science_api,node_regime_api,node_coastal_api,node_geo_api,node_zone_api,node_heavy_api,node_live_api,node_noaa_service toneAmber
class node_forecast_models,node_district_products,node_heavy_models,node_live_pipeline toneMint
class node_gefs_source,node_imd_source,node_frozen_evidence,node_verification toneRose
```

## Components

### Web presentation

- [Science dashboard](https://github.com/iadityachourasia/varshasetu/tree/master/frontend-v2/src/app): `frontend-v2/src/app`
- [API clients](https://github.com/iadityachourasia/varshasetu/tree/master/frontend-v2/src/lib/api): `frontend-v2/src/lib/api`

### Read-only API

- [FastAPI service](https://github.com/iadityachourasia/varshasetu/blob/master/backend/main.py): `backend/main.py`
- [API routers](https://github.com/iadityachourasia/varshasetu/tree/master/backend/app/api): `backend/app/api`
- [Operational products](https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/api/operational.py): `backend/app/api/operational.py`
- [Evidence endpoints](https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/api/evidence.py): `backend/app/api/evidence.py`
- [Science endpoints](https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/api/science.py): `backend/app/api/science.py`
- [Regime endpoints](https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/api/regime_validation.py): `backend/app/api/regime_validation.py`
- [Coastal regimes](https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/api/coastal_regime.py): `backend/app/api/coastal_regime.py`
- [Geo-aware products](https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/api/geoaware.py): `backend/app/api/geoaware.py`
- [Zone products](https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/api/zones.py): `backend/app/api/zones.py`
- [Heavy-rain products](https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/api/heavy_rain.py): `backend/app/api/heavy_rain.py`
- [Live-cycle endpoint](https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/api/live.py): `backend/app/api/live.py`

### Forecast science

- [Regime-aware correction](https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/ml/phase2b.py): `backend/app/ml/phase2b.py`
- [District products](https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/ml/district_product.py): `backend/app/ml/district_product.py`
- [Heavy-rain models](https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/ml/heavy_rain_product.py): `backend/app/ml/heavy_rain_product.py`
- [Live inference pipeline](https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/live/pipeline.py): `backend/app/live/pipeline.py`

### Data and verification

- [NOAA GEFS archive](https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/data_sources/noaa_gefs.py): `backend/app/data_sources/noaa_gefs.py`
- [IMD rainfall archive](https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/data_sources/imd_rainfall.py): `backend/app/data_sources/imd_rainfall.py`
- [Frozen evidence](https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/api/evidence.py): `backend/app/api/evidence.py`
- [Verification metrics](https://github.com/iadityachourasia/varshasetu/blob/master/backend/app/verification/metrics.py): `backend/app/verification/metrics.py`

### Other components

- **Research user**
- **NOAA GEFS source**

## Connections

- Research user → Science dashboard: explores results (evidence: `README.md`)
- Science dashboard → API clients: requests products (evidence: `README.md`)
- FastAPI service → API routers: mounts routers (evidence: `backend/main.py`)
- API routers → Operational products: routes requests (evidence: `backend/main.py`)
- API routers → Evidence endpoints: routes requests (evidence: `backend/main.py`)
- API routers → Science endpoints: routes requests (evidence: `backend/main.py`)
- API routers → Regime endpoints: routes requests (evidence: `backend/main.py`)
- API routers → Coastal regimes: routes requests (evidence: `backend/main.py`)
- API routers → Geo-aware products: routes requests (evidence: `backend/main.py`)
- API routers → Zone products: routes requests (evidence: `backend/main.py`)
- API routers → Heavy-rain products: routes requests (evidence: `backend/main.py`)
- API routers → Live-cycle endpoint: routes requests (evidence: `backend/main.py`)
- NOAA GEFS archive → Regime-aware correction: provides forecasts (evidence: `README.md`)
- Regime-aware correction → District products: produces district grids (evidence: `README.md`)
- Regime-aware correction → Heavy-rain models: estimates extremes (evidence: `README.md`)
- IMD rainfall archive → Verification metrics: reference observations (evidence: `README.md`)
- Regime-aware correction → Verification metrics: evaluated by (evidence: `README.md`)
- Evidence endpoints → Frozen evidence: verifies and serves (evidence: `backend/app/api/evidence.py`)
- Live-cycle endpoint → Live inference pipeline: runs inference (evidence: `backend/app/api/live.py`)
- Live inference pipeline → NOAA GEFS source: fetches forecast data (evidence: `backend/app/live/pipeline.py`)
