# biswajitbiswal-in/ritugyan architecture

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

- Interactive diagram: https://gitdiagram.com/biswajitbiswal-in/ritugyan
- Repository: https://github.com/biswajitbiswal-in/ritugyan

## Overview

RituGyan post-processes monsoon rainfall forecasts: align forecast and atmospheric grids with observed rainfall, classify the weather regime, then apply regime-conditioned correction and provide rainfall-risk outputs for users. The graph preserves the README’s documented district aggregation, verification, API, and dashboard capabilities, though their implementation is not shown in the sampled source. Batch assembly, synoptic feature extraction, and feature storage have direct source evidence; other documented subsystem paths are represented by their existing directories.

Main entry points: [`src/features/preprocessing.py`](https://github.com/biswajitbiswal-in/ritugyan/blob/main/src/features/preprocessing.py) (Feature preprocessing), [`src/models/stage2_correction`](https://github.com/biswajitbiswal-in/ritugyan/tree/main/src/models/stage2_correction) (Conditional correction), [`src/features/batch_pipeline.py`](https://github.com/biswajitbiswal-in/ritugyan/blob/main/src/features/batch_pipeline.py) (Batch assembly), [`src/ingestion/readers.py`](https://github.com/biswajitbiswal-in/ritugyan/blob/main/src/ingestion/readers.py) (Dataset readers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data preparation"]
  node_acquisition["GFS acquisition<br/>[gfs_downloader.py]"]
  node_readers["Dataset readers<br/>[readers.py]"]
  node_inspection["Data inspection<br/>[inspector.py]"]
  node_alignment["Grid alignment<br/>[spatial.py]"]
  node_preprocessing["Feature preprocessing<br/>[preprocessing.py]"]
  node_batch["Batch assembly<br/>[batch_pipeline.py]"]
  node_store[("Feature store<br/>[feature_store.py]")]
end

subgraph group_forecast["Forecast processing"]
  node_synoptic["Synoptic features<br/>[synoptic.py]"]
  node_regimes["Regime classification<br/>[regimes.py]"]
  node_stage1["Regime model stage"]
  node_stage2["Conditional correction"]
end

subgraph group_outputs["Products and delivery"]
  node_risk["Heavy-rain probabilities"]
  node_districts["District aggregation"]
  node_api["Forecast API"]
  node_dashboard["Interactive dashboard"]
end

subgraph group_verify["Verification"]
  node_verification["Regime-stratified verification"]
end

node_archives(("Forecast and observation data"))
node_noaa(("NOAA GFS"))
node_users(("Forecast users"))

node_noaa -->|"provides forecast data"| node_acquisition
node_acquisition -->|"writes forecast files"| node_readers
node_archives -->|"supplies datasets"| node_readers
node_readers -->|"opens for inspection"| node_inspection
node_readers -->|"opens for processing"| node_preprocessing
node_preprocessing -->|"slices common grids"| node_alignment
node_batch -->|"builds aligned samples"| node_preprocessing
node_batch -->|"extracts indices"| node_synoptic
node_batch -->|"classifies samples"| node_regimes
node_batch -->|"saves samples"| node_store
node_synoptic -->|"provides features"| node_regimes
node_preprocessing -->|"supplies forecast fields"| node_stage1
node_regimes -->|"supplies regime label"| node_stage1
node_stage1 -->|"provides regime"| node_stage2
node_preprocessing -->|"supplies predictors"| node_stage2
node_stage2 -->|"estimates exceedance risk"| node_risk
node_stage2 -->|"provides corrected grids"| node_districts
node_risk -->|"serves probabilities"| node_api
node_districts -->|"serves aggregates"| node_api
node_api -->|"provides forecast service"| node_dashboard
node_dashboard -->|"presents forecasts"| node_users
node_stage2 -->|"provides corrected forecasts"| node_verification
node_archives -->|"provides observations"| node_verification

click node_acquisition "https://github.com/biswajitbiswal-in/ritugyan/blob/main/src/ingestion/gfs_downloader.py"
click node_readers "https://github.com/biswajitbiswal-in/ritugyan/blob/main/src/ingestion/readers.py"
click node_inspection "https://github.com/biswajitbiswal-in/ritugyan/blob/main/src/ingestion/inspector.py"
click node_alignment "https://github.com/biswajitbiswal-in/ritugyan/blob/main/src/ingestion/spatial.py"
click node_preprocessing "https://github.com/biswajitbiswal-in/ritugyan/blob/main/src/features/preprocessing.py"
click node_batch "https://github.com/biswajitbiswal-in/ritugyan/blob/main/src/features/batch_pipeline.py"
click node_synoptic "https://github.com/biswajitbiswal-in/ritugyan/blob/main/src/features/synoptic.py"
click node_regimes "https://github.com/biswajitbiswal-in/ritugyan/blob/main/src/features/regimes.py"
click node_store "https://github.com/biswajitbiswal-in/ritugyan/blob/main/src/features/feature_store.py"
click node_stage1 "https://github.com/biswajitbiswal-in/ritugyan/tree/main/src/models/stage1_regime"
click node_stage2 "https://github.com/biswajitbiswal-in/ritugyan/tree/main/src/models/stage2_correction"
click node_risk "https://github.com/biswajitbiswal-in/ritugyan/tree/main/src/models/stage2_correction"
click node_districts "https://github.com/biswajitbiswal-in/ritugyan/tree/main/src"
click node_api "https://github.com/biswajitbiswal-in/ritugyan/tree/main/src/api/routes"
click node_dashboard "https://github.com/biswajitbiswal-in/ritugyan/tree/main/src/ui"
click node_verification "https://github.com/biswajitbiswal-in/ritugyan/tree/main/src/evaluation"

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_acquisition,node_readers,node_inspection,node_alignment,node_preprocessing,node_batch,node_store,node_users toneBlue
class node_synoptic,node_regimes,node_stage1,node_stage2 toneAmber
class node_risk,node_districts,node_api,node_dashboard toneMint
class node_verification toneRose
class node_archives,node_noaa toneIndigo
```

## Components

### Data preparation

- [GFS acquisition](https://github.com/biswajitbiswal-in/ritugyan/blob/main/src/ingestion/gfs_downloader.py): `src/ingestion/gfs_downloader.py`
- [Dataset readers](https://github.com/biswajitbiswal-in/ritugyan/blob/main/src/ingestion/readers.py): `src/ingestion/readers.py`
- [Data inspection](https://github.com/biswajitbiswal-in/ritugyan/blob/main/src/ingestion/inspector.py): `src/ingestion/inspector.py`
- [Grid alignment](https://github.com/biswajitbiswal-in/ritugyan/blob/main/src/ingestion/spatial.py): `src/ingestion/spatial.py`
- [Feature preprocessing](https://github.com/biswajitbiswal-in/ritugyan/blob/main/src/features/preprocessing.py): `src/features/preprocessing.py`
- [Batch assembly](https://github.com/biswajitbiswal-in/ritugyan/blob/main/src/features/batch_pipeline.py): `src/features/batch_pipeline.py`
- [Feature store](https://github.com/biswajitbiswal-in/ritugyan/blob/main/src/features/feature_store.py): `src/features/feature_store.py`

### Forecast processing

- [Synoptic features](https://github.com/biswajitbiswal-in/ritugyan/blob/main/src/features/synoptic.py): `src/features/synoptic.py`
- [Regime classification](https://github.com/biswajitbiswal-in/ritugyan/blob/main/src/features/regimes.py): `src/features/regimes.py`
- [Regime model stage](https://github.com/biswajitbiswal-in/ritugyan/tree/main/src/models/stage1_regime): `src/models/stage1_regime`
- [Conditional correction](https://github.com/biswajitbiswal-in/ritugyan/tree/main/src/models/stage2_correction): `src/models/stage2_correction`

### Products and delivery

- [Heavy-rain probabilities](https://github.com/biswajitbiswal-in/ritugyan/tree/main/src/models/stage2_correction): `src/models/stage2_correction`
- [District aggregation](https://github.com/biswajitbiswal-in/ritugyan/tree/main/src): `src`
- [Forecast API](https://github.com/biswajitbiswal-in/ritugyan/tree/main/src/api/routes): `src/api/routes`
- [Interactive dashboard](https://github.com/biswajitbiswal-in/ritugyan/tree/main/src/ui): `src/ui`

### Verification

- [Regime-stratified verification](https://github.com/biswajitbiswal-in/ritugyan/tree/main/src/evaluation): `src/evaluation`

### Other components

- **Forecast and observation data**
- **NOAA GFS**
- **Forecast users**

## Connections

- NOAA GFS → GFS acquisition: provides forecast data
- GFS acquisition → Dataset readers: writes forecast files
- Forecast and observation data → Dataset readers: supplies datasets
- Dataset readers → Data inspection: opens for inspection
- Dataset readers → Feature preprocessing: opens for processing
- Feature preprocessing → Grid alignment: slices common grids
- Batch assembly → Feature preprocessing: builds aligned samples
- Batch assembly → Synoptic features: extracts indices
- Batch assembly → Regime classification: classifies samples
- Batch assembly → Feature store: saves samples
- Synoptic features → Regime classification: provides features
- Feature preprocessing → Regime model stage: supplies forecast fields
- Regime classification → Regime model stage: supplies regime label
- Regime model stage → Conditional correction: provides regime
- Feature preprocessing → Conditional correction: supplies predictors
- Conditional correction → Heavy-rain probabilities: estimates exceedance risk
- Conditional correction → District aggregation: provides corrected grids
- Heavy-rain probabilities → Forecast API: serves probabilities
- District aggregation → Forecast API: serves aggregates
- Forecast API → Interactive dashboard: provides forecast service
- Interactive dashboard → Forecast users: presents forecasts
- Conditional correction → Regime-stratified verification: provides corrected forecasts
- Forecast and observation data → Regime-stratified verification: provides observations