# prakhar9642/varuna architecture

> Architecture diagram of the GitHub repository prakhar9642/varuna, 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/prakhar9642/varuna
- Repository: https://github.com/prakhar9642/varuna

## Overview

VARUNA turns global NWP model data into region-level Indian forecasts, blending member predictions with an error-predicting meta-model where trained and serving explicit fallback weights otherwise. Users enter through the React command centre or focused forecast, skill, extremes, explainability, model, and health views; the UI fetches backend API data and presents provenance and validation state. Backend pipeline modules support aligned training and skill reports. Unsampled subsystems are included only where README or source-index references establish their role; their internal call paths are not inferred.

Main entry points: [`src/App.jsx`](https://github.com/prakhar9642/varuna/blob/main/src/App.jsx) (Route shell), [`varuna-backend/app/services/blend_service.py`](https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/services/blend_service.py) (Forecast blend service), [`src/services/api.js`](https://github.com/prakhar9642/varuna/blob/main/src/services/api.js) (API client), [`varuna-backend/app/science/run_pipeline.py`](https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/science/run_pipeline.py) (Training pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend experience"]
  node_app["Route shell<br/>[App.jsx]"]
  node_command["Command centre<br/>[CommandCentre.jsx]"]
  node_forecast_ui["Forecast views<br/>[Forecast.jsx]"]
  node_insight_ui["Skill and explain<br/>[Skill.jsx]"]
  node_extremes_ui["Extremes monitor<br/>[Extremes.jsx]"]
  node_models_ui["Models view<br/>[Models.jsx]"]
  node_health_ui["System health<br/>[SystemHealth.jsx]"]
  node_store["Selection and regional state<br/>[useStore.js]"]
  node_api_client["API client<br/>[api.js]"]
  node_ui_reference["Display reference data<br/>[referenceData.js]"]
  node_verification["Historical verification"]
end

subgraph group_api["Backend API"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_api_routes["Endpoint routes"]
  node_config["Regions and model config<br/>[config.py]"]
end

subgraph group_forecast["Forecast science"]
  node_blend["Forecast blend service<br/>[blend_service.py]"]
  node_regime["Regime classification<br/>[regime.py]"]
  node_weighting["Member weighting<br/>[weighting.py]"]
  node_meta["Error meta-model<br/>[meta_model.py]"]
end

subgraph group_training["Training and verification"]
  node_pipeline["Training pipeline<br/>[run_pipeline.py]"]
  node_alignment["Forecast-reference alignment<br/>[alignment.py]"]
  node_science_verify["Skill evaluation<br/>[verification.py]"]
end

subgraph group_integrations["Data integrations"]
  node_provider["Forecast provider<br/>[open_meteo.py]"]
  node_cache[("Response cache<br/>[cache.py]")]
end

node_user(("Weather analyst"))
node_open_meteo["Open-Meteo services"]
node_era5["ERA5 archive"]

node_user -->|"opens"| node_app
node_app -->|"routes to"| node_command
node_app -->|"routes to"| node_forecast_ui
node_app -->|"routes to"| node_insight_ui
node_app -->|"routes to"| node_extremes_ui
node_app -->|"routes to"| node_models_ui
node_app -->|"routes to"| node_health_ui
node_command -->|"reads and updates"| node_store
node_command -->|"uses metadata"| node_ui_reference
node_forecast_ui -->|"reads selections"| node_store
node_insight_ui -->|"reads selections"| node_store
node_extremes_ui -.->|"fetches extremes"| node_api_client
node_models_ui -.->|"fetches model data"| node_api_client
node_health_ui -.->|"fetches status"| node_api_client
node_store -->|"requests regions and forecasts"| node_api_client
node_api_client -->|"HTTP API requests"| node_api_app
node_api_app -->|"registers routers"| node_api_routes
node_api_app -->|"serves health payload"| node_blend
node_api_routes -->|"calls service"| node_blend
node_blend -->|"loads forecasts"| node_provider
node_blend -->|"predicts member errors"| node_meta
node_blend -->|"derives blend weights"| node_weighting
node_blend -->|"classifies regime"| node_regime
node_provider -->|"uses cache"| node_cache
node_provider -->|"fetches model data"| node_open_meteo
node_pipeline -->|"collects aligned rows"| node_alignment
node_pipeline -->|"trains bundle"| node_meta
node_pipeline -->|"evaluates skill"| node_science_verify
node_pipeline -->|"builds weight reports"| node_weighting
node_alignment -->|"collects forecasts"| node_provider
node_alignment -.->|"retrieves reference data"| node_era5
node_verification -.->|"checks API data"| node_api_client
node_api_app -->|"reads settings"| node_config

click node_app "https://github.com/prakhar9642/varuna/blob/main/src/App.jsx"
click node_command "https://github.com/prakhar9642/varuna/blob/main/src/pages/CommandCentre.jsx"
click node_forecast_ui "https://github.com/prakhar9642/varuna/blob/main/src/pages/Forecast.jsx"
click node_insight_ui "https://github.com/prakhar9642/varuna/blob/main/src/pages/Skill.jsx"
click node_extremes_ui "https://github.com/prakhar9642/varuna/blob/main/src/pages/Extremes.jsx"
click node_models_ui "https://github.com/prakhar9642/varuna/blob/main/src/pages/Models.jsx"
click node_health_ui "https://github.com/prakhar9642/varuna/blob/main/src/pages/SystemHealth.jsx"
click node_store "https://github.com/prakhar9642/varuna/blob/main/src/store/useStore.js"
click node_api_client "https://github.com/prakhar9642/varuna/blob/main/src/services/api.js"
click node_ui_reference "https://github.com/prakhar9642/varuna/blob/main/src/data/referenceData.js"
click node_verification "https://github.com/prakhar9642/varuna/tree/main/src/verification"
click node_api_app "https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/main.py"
click node_api_routes "https://github.com/prakhar9642/varuna/tree/main/varuna-backend/app/api"
click node_blend "https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/services/blend_service.py"
click node_regime "https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/science/regime.py"
click node_weighting "https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/science/weighting.py"
click node_meta "https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/science/meta_model.py"
click node_provider "https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/providers/open_meteo.py"
click node_cache "https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/providers/cache.py"
click node_pipeline "https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/science/run_pipeline.py"
click node_alignment "https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/science/alignment.py"
click node_science_verify "https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/science/verification.py"
click node_config "https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/config.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_command,node_forecast_ui,node_insight_ui,node_extremes_ui,node_models_ui,node_health_ui,node_store,node_api_client,node_ui_reference,node_verification toneBlue
class node_api_app,node_api_routes,node_config toneAmber
class node_blend,node_regime,node_weighting,node_meta toneMint
class node_pipeline,node_alignment,node_science_verify toneRose
class node_provider,node_cache,node_user,node_open_meteo,node_era5 toneIndigo
```

## Components

### Frontend experience

- [Route shell](https://github.com/prakhar9642/varuna/blob/main/src/App.jsx): `src/App.jsx`
- [Command centre](https://github.com/prakhar9642/varuna/blob/main/src/pages/CommandCentre.jsx): `src/pages/CommandCentre.jsx`
- [Forecast views](https://github.com/prakhar9642/varuna/blob/main/src/pages/Forecast.jsx): `src/pages/Forecast.jsx`
- [Skill and explain](https://github.com/prakhar9642/varuna/blob/main/src/pages/Skill.jsx): `src/pages/Skill.jsx`
- [Extremes monitor](https://github.com/prakhar9642/varuna/blob/main/src/pages/Extremes.jsx): `src/pages/Extremes.jsx`
- [Models view](https://github.com/prakhar9642/varuna/blob/main/src/pages/Models.jsx): `src/pages/Models.jsx`
- [System health](https://github.com/prakhar9642/varuna/blob/main/src/pages/SystemHealth.jsx): `src/pages/SystemHealth.jsx`
- [Selection and regional state](https://github.com/prakhar9642/varuna/blob/main/src/store/useStore.js): `src/store/useStore.js`
- [API client](https://github.com/prakhar9642/varuna/blob/main/src/services/api.js): `src/services/api.js`
- [Display reference data](https://github.com/prakhar9642/varuna/blob/main/src/data/referenceData.js): `src/data/referenceData.js`
- [Historical verification](https://github.com/prakhar9642/varuna/tree/main/src/verification): `src/verification`

### Backend API

- [FastAPI application](https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/main.py): `varuna-backend/app/main.py`
- [Endpoint routes](https://github.com/prakhar9642/varuna/tree/main/varuna-backend/app/api): `varuna-backend/app/api`
- [Regions and model config](https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/config.py): `varuna-backend/app/config.py`

### Forecast science

- [Forecast blend service](https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/services/blend_service.py): `varuna-backend/app/services/blend_service.py`
- [Regime classification](https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/science/regime.py): `varuna-backend/app/science/regime.py`
- [Member weighting](https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/science/weighting.py): `varuna-backend/app/science/weighting.py`
- [Error meta-model](https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/science/meta_model.py): `varuna-backend/app/science/meta_model.py`

### Training and verification

- [Training pipeline](https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/science/run_pipeline.py): `varuna-backend/app/science/run_pipeline.py`
- [Forecast-reference alignment](https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/science/alignment.py): `varuna-backend/app/science/alignment.py`
- [Skill evaluation](https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/science/verification.py): `varuna-backend/app/science/verification.py`

### Data integrations

- [Forecast provider](https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/providers/open_meteo.py): `varuna-backend/app/providers/open_meteo.py`
- [Response cache](https://github.com/prakhar9642/varuna/blob/main/varuna-backend/app/providers/cache.py): `varuna-backend/app/providers/cache.py`

### Other components

- **Weather analyst**
- **Open-Meteo services**
- **ERA5 archive**

## Connections

- Weather analyst → Route shell: opens (evidence: `src/App.jsx`)
- Route shell → Command centre: routes to (evidence: `src/App.jsx`)
- Route shell → Forecast views: routes to (evidence: `src/App.jsx`)
- Route shell → Skill and explain: routes to (evidence: `src/App.jsx`)
- Route shell → Extremes monitor: routes to (evidence: `src/App.jsx`)
- Route shell → Models view: routes to (evidence: `src/App.jsx`)
- Route shell → System health: routes to (evidence: `src/App.jsx`)
- Command centre → Selection and regional state: reads and updates (evidence: `src/pages/CommandCentre.jsx`)
- Command centre → Display reference data: uses metadata (evidence: `src/pages/CommandCentre.jsx`)
- Forecast views → Selection and regional state: reads selections (evidence: `src/pages/Forecast.jsx`)
- Skill and explain → Selection and regional state: reads selections (evidence: `src/pages/Skill.jsx`)
- Extremes monitor → API client: fetches extremes (evidence: `README.md`)
- Models view → API client: fetches model data (evidence: `README.md`)
- System health → API client: fetches status (evidence: `README.md`)
- Selection and regional state → API client: requests regions and forecasts (evidence: `src/store/useStore.js`)
- API client → FastAPI application: HTTP API requests (evidence: `README.md`)
- FastAPI application → Endpoint routes: registers routers (evidence: `varuna-backend/app/main.py`)
- FastAPI application → Forecast blend service: serves health payload (evidence: `varuna-backend/app/main.py`)
- Endpoint routes → Forecast blend service: calls service (evidence: `varuna-backend/app/api/routes_forecast.py`)
- Forecast blend service → Forecast provider: loads forecasts (evidence: `varuna-backend/app/services/blend_service.py`)
- Forecast blend service → Error meta-model: predicts member errors (evidence: `varuna-backend/app/services/blend_service.py`)
- Forecast blend service → Member weighting: derives blend weights (evidence: `varuna-backend/app/services/blend_service.py`)
- Forecast blend service → Regime classification: classifies regime (evidence: `varuna-backend/app/services/blend_service.py`)
- Forecast provider → Response cache: uses cache (evidence: `varuna-backend/app/providers/open_meteo.py`)
- Forecast provider → Open-Meteo services: fetches model data (evidence: `README.md`)
- Training pipeline → Forecast-reference alignment: collects aligned rows (evidence: `varuna-backend/app/science/run_pipeline.py`)
- Training pipeline → Error meta-model: trains bundle (evidence: `varuna-backend/app/science/run_pipeline.py`)
- Training pipeline → Skill evaluation: evaluates skill (evidence: `varuna-backend/app/science/run_pipeline.py`)
- Training pipeline → Member weighting: builds weight reports (evidence: `varuna-backend/app/science/run_pipeline.py`)
- Forecast-reference alignment → Forecast provider: collects forecasts (evidence: `varuna-backend/app/science/alignment.py`)
- Forecast-reference alignment → ERA5 archive: retrieves reference data (evidence: `README.md`)
- Historical verification → API client: checks API data (evidence: `README.md`)
- FastAPI application → Regions and model config: reads settings (evidence: `varuna-backend/app/main.py`)