# atmosync/weavr architecture

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

- Interactive diagram: https://gitdiagram.com/atmosync/weavr
- Repository: https://github.com/atmosync/weavr

## Overview

WEAVR blends rainfall forecasts from multiple models on a common India grid, calibrates forecast distributions and probabilities, and evaluates results using held-out verification. Its dashboard exposes forecast, weight, skill, and extreme-probability views through a read-only API; a separate daily pipeline applies fitted regional weights to available forecasts. The README documents several capabilities whose detailed implementation was not sampled, so those links reflect documented behavior rather than inspected call sites.

Main entry points: [`src/weavr/data`](https://github.com/atmosync/weavr/tree/main/src/weavr/data) (Forecast and observation loaders), [`scripts/run_daily_pipeline.py`](https://github.com/atmosync/weavr/blob/main/scripts/run_daily_pipeline.py) (Daily forecast pipeline), [`dashboard-web/js/main.js`](https://github.com/atmosync/weavr/blob/main/dashboard-web/js/main.js) (View navigation), [`dashboard-web/js/api.js`](https://github.com/atmosync/weavr/blob/main/dashboard-web/js/api.js) (API fetch wrappers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Data and grid"]
  node_source_loaders["Forecast and observation loaders"]
  node_heppi["HEPPI reference loader<br/>[heppi_reference.py]"]
  node_grid["Common grid<br/>[grid.py]"]
end

subgraph group_methods["Blend and calibrate"]
  node_ensemble["Ensemble handling<br/>[ensemble.py]"]
  node_weights["Regional weights<br/>[weighting.py]"]
  node_regions["Region assignment<br/>[regions.py]"]
  node_emos["EMOS calibration<br/>[emos.py]"]
  node_bma["BMA calibration<br/>[bma.py]"]
  node_regimes["Regime-conditioned weights"]
end

subgraph group_evidence["Verification"]
  node_verify["Forecast metrics<br/>[verify.py]"]
  node_splits["Held-out splits<br/>[splits.py]"]
  node_significance["Statistical tests<br/>[significance.py]"]
end

subgraph group_operations["Daily operations"]
  node_daily["Daily forecast pipeline"]
  node_drift["Drift detection<br/>[drift.py]"]
  node_renormalize["Weight renormalization<br/>[renormalize.py]"]
end

subgraph group_dashboard["Dashboard"]
  node_frontend["View navigation<br/>[main.js]"]
  node_web_api["API fetch wrappers<br/>[api.js]"]
  node_weight_view["Weight map<br/>[weightMap.js]"]
  node_skill_view["Skill trends<br/>[skillTrends.js]"]
  node_blend_view["Blended map<br/>[blendedMap.js]"]
  node_prob_view["Extreme probabilities"]
  node_basemap["Geographic map<br/>[basemapMap.js]"]
  node_api["Read-only JSON API<br/>[api.py]"]
  node_loading["Dashboard data shaping<br/>[data_loading.py]"]
  node_colors["IMD color scheme<br/>[colors.py]"]
end

node_graphcast(("GraphCast"))
node_hres(("HRES"))
node_ifs(("IFS ensemble"))
node_imd(("IMD rainfall"))
node_ecmwf_feed(("ECMWF open data"))
node_user(("Dashboard user"))

node_ecmwf_feed -->|"provides forecasts"| node_source_loaders
node_graphcast -->|"provides forecasts"| node_source_loaders
node_hres -->|"provides forecasts"| node_source_loaders
node_ifs -->|"provides forecasts"| node_source_loaders
node_imd -->|"provides observations"| node_source_loaders
node_imd -.->|"paired reference data"| node_heppi
node_source_loaders -->|"load for regridding"| node_grid
node_heppi -->|"uses common coordinates"| node_grid
node_grid -->|"supplies gridded fields"| node_weights
node_grid -->|"supplies gridded fields"| node_ensemble
node_regions -->|"defines regions"| node_weights
node_weights -->|"provides fitted weights"| node_daily
node_daily -->|"fetches current data"| node_source_loaders
node_daily -->|"assigns grid regions"| node_regions
node_daily -->|"redistributes missing-source weights"| node_renormalize
node_daily -->|"checks performance drift"| node_drift
node_daily -->|"scores forecasts"| node_verify
node_ensemble -->|"calibrates distributions"| node_emos
node_ensemble -->|"fits mixture blend"| node_bma
node_regions -->|"supplies spatial regions"| node_regimes
node_weights -->|"regional baseline"| node_regimes
node_splits -->|"sets evaluation windows"| node_verify
node_verify -->|"supplies paired scores"| node_significance
node_user -->|"selects views"| node_frontend
node_frontend -->|"renders view"| node_weight_view
node_frontend -->|"renders view"| node_skill_view
node_frontend -->|"renders view"| node_blend_view
node_frontend -->|"renders view"| node_prob_view
node_weight_view -->|"requests weight data"| node_web_api
node_skill_view -->|"requests skill data"| node_web_api
node_blend_view -->|"requests forecast grid"| node_web_api
node_prob_view -->|"requests probability grid"| node_web_api
node_web_api -->|"fetches JSON"| node_api
node_api -->|"loads and shapes data"| node_loading
node_api -->|"loads color identities"| node_colors
node_blend_view -.->|"overlays forecast grid"| node_basemap
node_prob_view -.->|"overlays probability grid"| node_basemap
node_basemap -.->|"checks local basemap"| node_api

click node_source_loaders "https://github.com/atmosync/weavr/tree/main/src/weavr/data"
click node_heppi "https://github.com/atmosync/weavr/blob/main/src/weavr/data/heppi_reference.py"
click node_grid "https://github.com/atmosync/weavr/blob/main/src/weavr/grid.py"
click node_ensemble "https://github.com/atmosync/weavr/blob/main/src/weavr/ensemble.py"
click node_weights "https://github.com/atmosync/weavr/blob/main/src/weavr/weighting.py"
click node_regions "https://github.com/atmosync/weavr/blob/main/src/weavr/regions.py"
click node_emos "https://github.com/atmosync/weavr/blob/main/src/weavr/emos.py"
click node_bma "https://github.com/atmosync/weavr/blob/main/src/weavr/bma.py"
click node_regimes "https://github.com/atmosync/weavr/blob/main/src/weavr/regime_weighting.py"
click node_verify "https://github.com/atmosync/weavr/blob/main/src/weavr/verify.py"
click node_splits "https://github.com/atmosync/weavr/blob/main/src/weavr/splits.py"
click node_significance "https://github.com/atmosync/weavr/blob/main/src/weavr/significance.py"
click node_daily "https://github.com/atmosync/weavr/blob/main/scripts/run_daily_pipeline.py"
click node_drift "https://github.com/atmosync/weavr/blob/main/src/weavr/drift.py"
click node_renormalize "https://github.com/atmosync/weavr/blob/main/src/weavr/renormalize.py"
click node_frontend "https://github.com/atmosync/weavr/blob/main/dashboard-web/js/main.js"
click node_web_api "https://github.com/atmosync/weavr/blob/main/dashboard-web/js/api.js"
click node_weight_view "https://github.com/atmosync/weavr/blob/main/dashboard-web/js/charts/weightMap.js"
click node_skill_view "https://github.com/atmosync/weavr/blob/main/dashboard-web/js/charts/skillTrends.js"
click node_blend_view "https://github.com/atmosync/weavr/blob/main/dashboard-web/js/charts/blendedMap.js"
click node_prob_view "https://github.com/atmosync/weavr/blob/main/dashboard-web/js/charts/extremeProbability.js"
click node_basemap "https://github.com/atmosync/weavr/blob/main/dashboard-web/js/charts/basemapMap.js"
click node_api "https://github.com/atmosync/weavr/blob/main/dashboard/api.py"
click node_loading "https://github.com/atmosync/weavr/blob/main/dashboard/data_loading.py"
click node_colors "https://github.com/atmosync/weavr/blob/main/dashboard/colors.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_source_loaders,node_heppi,node_grid,node_user toneBlue
class node_ensemble,node_weights,node_regions,node_emos,node_bma,node_regimes toneAmber
class node_verify,node_splits,node_significance toneMint
class node_daily,node_drift,node_renormalize toneRose
class node_frontend,node_web_api,node_weight_view,node_skill_view,node_blend_view,node_prob_view,node_basemap,node_api,node_loading,node_colors,node_graphcast,node_hres,node_ifs,node_imd,node_ecmwf_feed toneIndigo
```

## Components

### Data and grid

- [Forecast and observation loaders](https://github.com/atmosync/weavr/tree/main/src/weavr/data): `src/weavr/data`
- [HEPPI reference loader](https://github.com/atmosync/weavr/blob/main/src/weavr/data/heppi_reference.py): `src/weavr/data/heppi_reference.py`
- [Common grid](https://github.com/atmosync/weavr/blob/main/src/weavr/grid.py): `src/weavr/grid.py`

### Blend and calibrate

- [Ensemble handling](https://github.com/atmosync/weavr/blob/main/src/weavr/ensemble.py): `src/weavr/ensemble.py`
- [Regional weights](https://github.com/atmosync/weavr/blob/main/src/weavr/weighting.py): `src/weavr/weighting.py`
- [Region assignment](https://github.com/atmosync/weavr/blob/main/src/weavr/regions.py): `src/weavr/regions.py`
- [EMOS calibration](https://github.com/atmosync/weavr/blob/main/src/weavr/emos.py): `src/weavr/emos.py`
- [BMA calibration](https://github.com/atmosync/weavr/blob/main/src/weavr/bma.py): `src/weavr/bma.py`
- [Regime-conditioned weights](https://github.com/atmosync/weavr/blob/main/src/weavr/regime_weighting.py): `src/weavr/regime_weighting.py`

### Verification

- [Forecast metrics](https://github.com/atmosync/weavr/blob/main/src/weavr/verify.py): `src/weavr/verify.py`
- [Held-out splits](https://github.com/atmosync/weavr/blob/main/src/weavr/splits.py): `src/weavr/splits.py`
- [Statistical tests](https://github.com/atmosync/weavr/blob/main/src/weavr/significance.py): `src/weavr/significance.py`

### Daily operations

- [Daily forecast pipeline](https://github.com/atmosync/weavr/blob/main/scripts/run_daily_pipeline.py): `scripts/run_daily_pipeline.py`
- [Drift detection](https://github.com/atmosync/weavr/blob/main/src/weavr/drift.py): `src/weavr/drift.py`
- [Weight renormalization](https://github.com/atmosync/weavr/blob/main/src/weavr/renormalize.py): `src/weavr/renormalize.py`

### Dashboard

- [View navigation](https://github.com/atmosync/weavr/blob/main/dashboard-web/js/main.js): `dashboard-web/js/main.js`
- [API fetch wrappers](https://github.com/atmosync/weavr/blob/main/dashboard-web/js/api.js): `dashboard-web/js/api.js`
- [Weight map](https://github.com/atmosync/weavr/blob/main/dashboard-web/js/charts/weightMap.js): `dashboard-web/js/charts/weightMap.js`
- [Skill trends](https://github.com/atmosync/weavr/blob/main/dashboard-web/js/charts/skillTrends.js): `dashboard-web/js/charts/skillTrends.js`
- [Blended map](https://github.com/atmosync/weavr/blob/main/dashboard-web/js/charts/blendedMap.js): `dashboard-web/js/charts/blendedMap.js`
- [Extreme probabilities](https://github.com/atmosync/weavr/blob/main/dashboard-web/js/charts/extremeProbability.js): `dashboard-web/js/charts/extremeProbability.js`
- [Geographic map](https://github.com/atmosync/weavr/blob/main/dashboard-web/js/charts/basemapMap.js): `dashboard-web/js/charts/basemapMap.js`
- [Read-only JSON API](https://github.com/atmosync/weavr/blob/main/dashboard/api.py): `dashboard/api.py`
- [Dashboard data shaping](https://github.com/atmosync/weavr/blob/main/dashboard/data_loading.py): `dashboard/data_loading.py`
- [IMD color scheme](https://github.com/atmosync/weavr/blob/main/dashboard/colors.py): `dashboard/colors.py`

### Other components

- **GraphCast**
- **HRES**
- **IFS ensemble**
- **IMD rainfall**
- **ECMWF open data**
- **Dashboard user**

## Connections

- ECMWF open data → Forecast and observation loaders: provides forecasts
- GraphCast → Forecast and observation loaders: provides forecasts
- HRES → Forecast and observation loaders: provides forecasts
- IFS ensemble → Forecast and observation loaders: provides forecasts
- IMD rainfall → Forecast and observation loaders: provides observations
- IMD rainfall → HEPPI reference loader: paired reference data
- Forecast and observation loaders → Common grid: load for regridding
- HEPPI reference loader → Common grid: uses common coordinates
- Common grid → Regional weights: supplies gridded fields
- Common grid → Ensemble handling: supplies gridded fields
- Region assignment → Regional weights: defines regions
- Regional weights → Daily forecast pipeline: provides fitted weights
- Daily forecast pipeline → Forecast and observation loaders: fetches current data
- Daily forecast pipeline → Region assignment: assigns grid regions
- Daily forecast pipeline → Weight renormalization: redistributes missing-source weights
- Daily forecast pipeline → Drift detection: checks performance drift
- Daily forecast pipeline → Forecast metrics: scores forecasts
- Ensemble handling → EMOS calibration: calibrates distributions
- Ensemble handling → BMA calibration: fits mixture blend
- Region assignment → Regime-conditioned weights: supplies spatial regions
- Regional weights → Regime-conditioned weights: regional baseline
- Held-out splits → Forecast metrics: sets evaluation windows
- Forecast metrics → Statistical tests: supplies paired scores
- Dashboard user → View navigation: selects views
- View navigation → Weight map: renders view
- View navigation → Skill trends: renders view
- View navigation → Blended map: renders view
- View navigation → Extreme probabilities: renders view
- Weight map → API fetch wrappers: requests weight data
- Skill trends → API fetch wrappers: requests skill data
- Blended map → API fetch wrappers: requests forecast grid
- Extreme probabilities → API fetch wrappers: requests probability grid
- API fetch wrappers → Read-only JSON API: fetches JSON
- Read-only JSON API → Dashboard data shaping: loads and shapes data
- Read-only JSON API → IMD color scheme: loads color identities
- Blended map → Geographic map: overlays forecast grid
- Extreme probabilities → Geographic map: overlays probability grid
- Geographic map → Read-only JSON API: checks local basemap