# techbots2026/stormsense architecture

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

- Interactive diagram: https://gitdiagram.com/techbots2026/stormsense
- Repository: https://github.com/techbots2026/stormsense

## Overview

StormSense is a West Bengal severe-weather nowcasting product: it turns live atmospheric inputs into calibrated, multi-horizon forecasts, spatial risk products and dashboard views. The principal workflow runs from the browser through the operational API and nowcast service to GFS input preparation and model inference, then serves map, point-risk and advisory information. The repository also contains a separate ERA5 data-preparation and model-training path. Several dashboard capabilities are documented in the README, but their implementation and wiring are not fully visible in the excerpts.

Main entry points: [`src/inference/nowcast_service.py`](https://github.com/techbots2026/stormsense/blob/master/src/inference/nowcast_service.py) (Nowcast service), [`backend/main.py`](https://github.com/techbots2026/stormsense/blob/master/backend/main.py) (Operational API), [`frontend/js/app.js`](https://github.com/techbots2026/stormsense/blob/master/frontend/js/app.js) (Dashboard views), [`src/inference/predictor.py`](https://github.com/techbots2026/stormsense/blob/master/src/inference/predictor.py) (Predictor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Dashboard"]
  node_dashboard["Dashboard views<br/>[app.js]"]
end

subgraph group_api["API and orchestration"]
  node_api_main["Operational API<br/>[main.py]"]
  node_service["Nowcast service<br/>[nowcast_service.py]"]
  node_api_app["Model API<br/>[app.py]"]
end

subgraph group_inputs["Weather inputs"]
  node_gfs["GFS harmonizer<br/>[gfs_live.py]"]
  node_observations["Surface observations"]
  node_radar["Radar feed"]
  node_satellite["INSAT archive<br/>[insat_archive.py]"]
  node_evidence["Now evidence<br/>[now_evidence.py]"]
end

subgraph group_forecast["Forecast and risk"]
  node_predictor["Predictor<br/>[predictor.py]"]
  node_v2model["V2 model<br/>[v2_model.py]"]
  node_advanced["Advanced model<br/>[advanced.py]"]
  node_riskmap["Risk maps<br/>[risk_map.py]"]
  node_risksurface["Risk surfaces<br/>[risk_surface.py]"]
  node_thresholds["Risk thresholds<br/>[risk_thresholds.py]"]
  node_targettime["Target timing<br/>[target_time.py]"]
  node_xai["Feature attribution<br/>[xai.py]"]
  node_calibration["Calibrated alerts<br/>[calibration.py]"]
  node_benchmark["Model benchmark<br/>[evaluate.py]"]
end

subgraph group_ml["Data and models"]
  node_config["Configuration<br/>[config.py]"]
  node_era5["ERA5 loader<br/>[era5_loader.py]"]
  node_preprocess["Preprocessing<br/>[preprocess.py]"]
  node_targets["Label generation<br/>[targets.py]"]
  node_normalize["Normalization<br/>[normalize.py]"]
  node_windowing["Windowing<br/>[windowing.py]"]
  node_dataset["V2 dataset<br/>[dataset_v2.py]"]
  node_dataset_plus["V2+ dataset<br/>[dataset_v2_plus.py]"]
end

node_operator(("Forecaster"))
node_gfs_source["NOAA GFS"]

node_operator -->|"views forecasts"| node_dashboard
node_dashboard -.->|"requests forecasts"| node_api_main
node_api_main -->|"uses service"| node_service
node_service -->|"fetches inputs"| node_gfs
node_gfs -->|"fetches analyses"| node_gfs_source
node_service -->|"runs inference"| node_predictor
node_predictor -->|"loads model"| node_v2model
node_predictor -->|"loads model"| node_advanced
node_service -->|"builds risk maps"| node_riskmap
node_service -->|"builds surfaces"| node_risksurface
node_service -->|"applies thresholds"| node_thresholds
node_service -->|"resolves leads"| node_targettime
node_service -->|"requests attribution"| node_xai
node_api_main -->|"renders observations"| node_observations
node_api_main -.->|"serves radar feed"| node_radar
node_api_main -.->|"serves satellite view"| node_satellite
node_api_main -->|"serves evidence"| node_evidence
node_api_app -->|"runs inference"| node_predictor
node_api_app -->|"serves risk map"| node_riskmap
node_api_main -->|"normalizes features"| node_normalize
node_preprocess -->|"loads reanalysis"| node_era5
node_preprocess -->|"generates labels"| node_targets
node_preprocess -->|"fits normalization"| node_normalize
node_dataset -->|"builds windows"| node_windowing
node_dataset_plus -->|"builds windows"| node_windowing
node_dataset -->|"normalizes inputs"| node_normalize
node_dataset_plus -->|"normalizes inputs"| node_normalize
node_predictor -->|"normalizes inputs"| node_normalize
node_riskmap -->|"uses thresholds"| node_thresholds
node_risksurface -->|"uses thresholds"| node_thresholds
node_evidence -->|"uses thresholds"| node_thresholds
node_dashboard -.->|"shows comparison"| node_benchmark
node_dashboard -.->|"shows calibrated bands"| node_calibration
node_dashboard -.->|"shows GIS layers"| node_risksurface
node_dashboard -.->|"shows attribution"| node_xai
node_config -.->|"configures inputs"| node_gfs

click node_dashboard "https://github.com/techbots2026/stormsense/blob/master/frontend/js/app.js"
click node_api_main "https://github.com/techbots2026/stormsense/blob/master/backend/main.py"
click node_service "https://github.com/techbots2026/stormsense/blob/master/src/inference/nowcast_service.py"
click node_api_app "https://github.com/techbots2026/stormsense/blob/master/src/api/app.py"
click node_gfs "https://github.com/techbots2026/stormsense/blob/master/src/inference/gfs_live.py"
click node_observations "https://github.com/techbots2026/stormsense/blob/master/src/inference/observation_surface.py"
click node_radar "https://github.com/techbots2026/stormsense/blob/master/src/inference/radar_observation.py"
click node_satellite "https://github.com/techbots2026/stormsense/blob/master/src/inference/insat_archive.py"
click node_evidence "https://github.com/techbots2026/stormsense/blob/master/src/inference/now_evidence.py"
click node_predictor "https://github.com/techbots2026/stormsense/blob/master/src/inference/predictor.py"
click node_v2model "https://github.com/techbots2026/stormsense/blob/master/src/models/v2_model.py"
click node_advanced "https://github.com/techbots2026/stormsense/blob/master/src/models/advanced.py"
click node_riskmap "https://github.com/techbots2026/stormsense/blob/master/src/inference/risk_map.py"
click node_risksurface "https://github.com/techbots2026/stormsense/blob/master/src/inference/risk_surface.py"
click node_thresholds "https://github.com/techbots2026/stormsense/blob/master/src/inference/risk_thresholds.py"
click node_targettime "https://github.com/techbots2026/stormsense/blob/master/src/inference/target_time.py"
click node_xai "https://github.com/techbots2026/stormsense/blob/master/src/inference/xai.py"
click node_config "https://github.com/techbots2026/stormsense/blob/master/src/utils/config.py"
click node_era5 "https://github.com/techbots2026/stormsense/blob/master/src/data/era5_loader.py"
click node_preprocess "https://github.com/techbots2026/stormsense/blob/master/src/data/preprocess.py"
click node_targets "https://github.com/techbots2026/stormsense/blob/master/src/features/targets.py"
click node_normalize "https://github.com/techbots2026/stormsense/blob/master/src/features/normalize.py"
click node_windowing "https://github.com/techbots2026/stormsense/blob/master/src/data/windowing.py"
click node_dataset "https://github.com/techbots2026/stormsense/blob/master/src/data/dataset_v2.py"
click node_dataset_plus "https://github.com/techbots2026/stormsense/blob/master/src/data/dataset_v2_plus.py"
click node_calibration "https://github.com/techbots2026/stormsense/blob/master/src/training/calibration.py"
click node_benchmark "https://github.com/techbots2026/stormsense/blob/master/scripts/evaluate.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_dashboard toneBlue
class node_api_main,node_service,node_api_app toneAmber
class node_gfs,node_observations,node_radar,node_satellite,node_evidence toneMint
class node_predictor,node_v2model,node_advanced,node_riskmap,node_risksurface,node_thresholds,node_targettime,node_xai,node_calibration,node_benchmark toneRose
class node_config,node_era5,node_preprocess,node_targets,node_normalize,node_windowing,node_dataset,node_dataset_plus,node_operator,node_gfs_source toneIndigo
```

## Components

### Dashboard

- [Dashboard views](https://github.com/techbots2026/stormsense/blob/master/frontend/js/app.js): `frontend/js/app.js`

### API and orchestration

- [Operational API](https://github.com/techbots2026/stormsense/blob/master/backend/main.py): `backend/main.py`
- [Nowcast service](https://github.com/techbots2026/stormsense/blob/master/src/inference/nowcast_service.py): `src/inference/nowcast_service.py`
- [Model API](https://github.com/techbots2026/stormsense/blob/master/src/api/app.py): `src/api/app.py`

### Weather inputs

- [GFS harmonizer](https://github.com/techbots2026/stormsense/blob/master/src/inference/gfs_live.py): `src/inference/gfs_live.py`
- [Surface observations](https://github.com/techbots2026/stormsense/blob/master/src/inference/observation_surface.py): `src/inference/observation_surface.py`
- [Radar feed](https://github.com/techbots2026/stormsense/blob/master/src/inference/radar_observation.py): `src/inference/radar_observation.py`
- [INSAT archive](https://github.com/techbots2026/stormsense/blob/master/src/inference/insat_archive.py): `src/inference/insat_archive.py`
- [Now evidence](https://github.com/techbots2026/stormsense/blob/master/src/inference/now_evidence.py): `src/inference/now_evidence.py`

### Forecast and risk

- [Predictor](https://github.com/techbots2026/stormsense/blob/master/src/inference/predictor.py): `src/inference/predictor.py`
- [V2 model](https://github.com/techbots2026/stormsense/blob/master/src/models/v2_model.py): `src/models/v2_model.py`
- [Advanced model](https://github.com/techbots2026/stormsense/blob/master/src/models/advanced.py): `src/models/advanced.py`
- [Risk maps](https://github.com/techbots2026/stormsense/blob/master/src/inference/risk_map.py): `src/inference/risk_map.py`
- [Risk surfaces](https://github.com/techbots2026/stormsense/blob/master/src/inference/risk_surface.py): `src/inference/risk_surface.py`
- [Risk thresholds](https://github.com/techbots2026/stormsense/blob/master/src/inference/risk_thresholds.py): `src/inference/risk_thresholds.py`
- [Target timing](https://github.com/techbots2026/stormsense/blob/master/src/inference/target_time.py): `src/inference/target_time.py`
- [Feature attribution](https://github.com/techbots2026/stormsense/blob/master/src/inference/xai.py): `src/inference/xai.py`
- [Calibrated alerts](https://github.com/techbots2026/stormsense/blob/master/src/training/calibration.py): `src/training/calibration.py`
- [Model benchmark](https://github.com/techbots2026/stormsense/blob/master/scripts/evaluate.py): `scripts/evaluate.py`

### Data and models

- [Configuration](https://github.com/techbots2026/stormsense/blob/master/src/utils/config.py): `src/utils/config.py`
- [ERA5 loader](https://github.com/techbots2026/stormsense/blob/master/src/data/era5_loader.py): `src/data/era5_loader.py`
- [Preprocessing](https://github.com/techbots2026/stormsense/blob/master/src/data/preprocess.py): `src/data/preprocess.py`
- [Label generation](https://github.com/techbots2026/stormsense/blob/master/src/features/targets.py): `src/features/targets.py`
- [Normalization](https://github.com/techbots2026/stormsense/blob/master/src/features/normalize.py): `src/features/normalize.py`
- [Windowing](https://github.com/techbots2026/stormsense/blob/master/src/data/windowing.py): `src/data/windowing.py`
- [V2 dataset](https://github.com/techbots2026/stormsense/blob/master/src/data/dataset_v2.py): `src/data/dataset_v2.py`
- [V2+ dataset](https://github.com/techbots2026/stormsense/blob/master/src/data/dataset_v2_plus.py): `src/data/dataset_v2_plus.py`

### Other components

- **Forecaster**
- **NOAA GFS**

## Connections

- Forecaster → Dashboard views: views forecasts
- Dashboard views → Operational API: requests forecasts
- Operational API → Nowcast service: uses service (evidence: `backend/main.py`)
- Nowcast service → GFS harmonizer: fetches inputs (evidence: `src/inference/nowcast_service.py`)
- GFS harmonizer → NOAA GFS: fetches analyses (evidence: `src/inference/gfs_live.py`)
- Nowcast service → Predictor: runs inference (evidence: `src/inference/nowcast_service.py`)
- Predictor → V2 model: loads model (evidence: `src/inference/predictor.py`)
- Predictor → Advanced model: loads model (evidence: `src/inference/predictor.py`)
- Nowcast service → Risk maps: builds risk maps (evidence: `src/inference/nowcast_service.py`)
- Nowcast service → Risk surfaces: builds surfaces (evidence: `src/inference/nowcast_service.py`)
- Nowcast service → Risk thresholds: applies thresholds (evidence: `src/inference/nowcast_service.py`)
- Nowcast service → Target timing: resolves leads (evidence: `src/inference/nowcast_service.py`)
- Nowcast service → Feature attribution: requests attribution (evidence: `src/inference/nowcast_service.py`)
- Operational API → Surface observations: renders observations (evidence: `backend/main.py`)
- Operational API → Radar feed: serves radar feed (evidence: `backend/main.py`)
- Operational API → INSAT archive: serves satellite view (evidence: `backend/main.py`)
- Operational API → Now evidence: serves evidence (evidence: `backend/main.py`)
- Model API → Predictor: runs inference (evidence: `src/api/app.py`)
- Model API → Risk maps: serves risk map (evidence: `src/api/app.py`)
- Operational API → Normalization: normalizes features (evidence: `backend/main.py`)
- Preprocessing → ERA5 loader: loads reanalysis (evidence: `src/data/preprocess.py`)
- Preprocessing → Label generation: generates labels (evidence: `src/data/preprocess.py`)
- Preprocessing → Normalization: fits normalization (evidence: `src/data/preprocess.py`)
- V2 dataset → Windowing: builds windows (evidence: `src/data/dataset_v2.py`)
- V2+ dataset → Windowing: builds windows (evidence: `src/data/dataset_v2_plus.py`)
- V2 dataset → Normalization: normalizes inputs (evidence: `src/data/dataset_v2.py`)
- V2+ dataset → Normalization: normalizes inputs (evidence: `src/data/dataset_v2_plus.py`)
- Predictor → Normalization: normalizes inputs (evidence: `src/inference/predictor.py`)
- Risk maps → Risk thresholds: uses thresholds (evidence: `src/inference/risk_map.py`)
- Risk surfaces → Risk thresholds: uses thresholds (evidence: `src/inference/risk_surface.py`)
- Now evidence → Risk thresholds: uses thresholds (evidence: `src/inference/now_evidence.py`)
- Dashboard views → Model benchmark: shows comparison
- Dashboard views → Calibrated alerts: shows calibrated bands
- Dashboard views → Risk surfaces: shows GIS layers
- Dashboard views → Feature attribution: shows attribution
- Configuration → GFS harmonizer: configures inputs
