# nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai architecture

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

- Interactive diagram: https://gitdiagram.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai
- Repository: https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai

## Overview

ThunderWatch AI is a multi-location thunderstorm-risk research prototype. Its user workflow is to request a station and time, then view +1h/+2h/+3h risk and data status in the dashboard. Historical replay looks up prepared features; live prediction fetches current weather, builds model features, and invokes the frozen multi-lead engine. The README also describes data synchronization, causal feature engineering, target generation, model training, and satellite/radar/lightning evidence research. Some pipeline wiring and UI details are documented but their source was not sampled, so those connections are limited to supported relationships.

Main entry points: [`src/inference/live_prediction_service.py`](https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/src/inference/live_prediction_service.py) (Live prediction), [`app.py`](https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/app.py) (Flask application), [`static/dashboard.js`](https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/static/dashboard.js) (Dashboard scripts), [`src/inference/multilead_service.py`](https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/src/inference/multilead_service.py) (Replay service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data_model["Data and models"]
  node_dataset_build["Synchronized data"]
  node_features["Causal features"]
  node_targets["Future targets"]
  node_training["Model training"]
  node_feature_builder["Live feature builder"]
end

subgraph group_inference["Prediction services"]
  node_replay_service["Replay service"]
  node_live_service["Live prediction"]
  node_live_adapter["Live feature adapter"]
  node_weather_client["Weather client"]
  node_engine["Multi-lead engine"]
end

subgraph group_presentation["API and dashboard"]
  node_api["Flask application<br/>[app.py]"]
  node_dashboard["Dashboard scripts<br/>[dashboard.js]"]
  node_geo_map["Geographic map<br/>[geo-map.js]"]
end

subgraph group_evidence["Evidence context"]
  node_satellite["Satellite replay context"]
end

node_user(("Dashboard user"))
node_openmeteo["Open-Meteo"]
node_gfs["GFS NWP"]
node_satellite_source["INSAT-3DR evidence"]

node_dataset_build -->|"supplies observations"| node_features
node_features -->|"provides predictors"| node_targets
node_targets -->|"trains on targets"| node_training
node_user -->|"uses dashboard"| node_dashboard
node_dashboard -->|"requests replay"| node_api
node_api -->|"dispatches replay"| node_replay_service
node_replay_service -->|"scores features"| node_engine
node_api -->|"dispatches live"| node_live_service
node_live_service -->|"fetches weather"| node_weather_client
node_weather_client -->|"requests data"| node_openmeteo
node_weather_client -->|"requests NWP"| node_gfs
node_live_service -->|"builds features"| node_live_adapter
node_live_adapter -->|"constructs vector"| node_feature_builder
node_live_service -->|"scores vector"| node_engine
node_replay_service -->|"attaches context"| node_satellite
node_satellite_source -.->|"supplies evidence"| node_satellite
node_api -->|"returns results"| node_dashboard
node_dashboard -->|"renders locations"| node_geo_map

click node_dataset_build "https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/dataset/build_synchronized_dataset_phase3.py"
click node_features "https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/dataset/multilocation/feature_engineering_phase3.py"
click node_targets "https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/dataset/multilocation/build_multilead_targets_phase5.py"
click node_training "https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/ml/train_v2_multilead_phase6.py"
click node_feature_builder "https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/src/features/v2_feature_builder.py"
click node_replay_service "https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/src/inference/multilead_service.py"
click node_live_service "https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/src/inference/live_prediction_service.py"
click node_live_adapter "https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/src/inference/live_feature_adapter.py"
click node_weather_client "https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/src/inference/live_openmeteo_client.py"
click node_engine "https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/src/inference/final_multi_lead_engine.py"
click node_api "https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/app.py"
click node_dashboard "https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/static/dashboard.js"
click node_geo_map "https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/static/geo-map.js"
click node_satellite "https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/src/inference/multilead_service.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_dataset_build,node_features,node_targets,node_training,node_feature_builder,node_user toneBlue
class node_replay_service,node_live_service,node_live_adapter,node_weather_client,node_engine toneAmber
class node_api,node_dashboard,node_geo_map toneMint
class node_satellite toneRose
class node_openmeteo,node_gfs,node_satellite_source toneIndigo
```

## Components

### Data and models

- [Synchronized data](https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/dataset/build_synchronized_dataset_phase3.py): `dataset/build_synchronized_dataset_phase3.py`
- [Causal features](https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/dataset/multilocation/feature_engineering_phase3.py): `dataset/multilocation/feature_engineering_phase3.py`
- [Future targets](https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/dataset/multilocation/build_multilead_targets_phase5.py): `dataset/multilocation/build_multilead_targets_phase5.py`
- [Model training](https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/ml/train_v2_multilead_phase6.py): `ml/train_v2_multilead_phase6.py`
- [Live feature builder](https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/src/features/v2_feature_builder.py): `src/features/v2_feature_builder.py`

### Prediction services

- [Replay service](https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/src/inference/multilead_service.py): `src/inference/multilead_service.py`
- [Live prediction](https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/src/inference/live_prediction_service.py): `src/inference/live_prediction_service.py`
- [Live feature adapter](https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/src/inference/live_feature_adapter.py): `src/inference/live_feature_adapter.py`
- [Weather client](https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/src/inference/live_openmeteo_client.py): `src/inference/live_openmeteo_client.py`
- [Multi-lead engine](https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/src/inference/final_multi_lead_engine.py): `src/inference/final_multi_lead_engine.py`

### API and dashboard

- [Flask application](https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/app.py): `app.py`
- [Dashboard scripts](https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/static/dashboard.js): `static/dashboard.js`
- [Geographic map](https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/static/geo-map.js): `static/geo-map.js`

### Evidence context

- [Satellite replay context](https://github.com/nachiket-mr360/aiml_thunderstorm_nowcasting_by_thunderwatch_ai/blob/main/src/inference/multilead_service.py): `src/inference/multilead_service.py`

### Other components

- **Dashboard user**
- **Open-Meteo**
- **GFS NWP**
- **INSAT-3DR evidence**

## Connections

- Synchronized data → Causal features: supplies observations
- Causal features → Future targets: provides predictors
- Future targets → Model training: trains on targets
- Dashboard user → Dashboard scripts: uses dashboard
- Dashboard scripts → Flask application: requests replay
- Flask application → Replay service: dispatches replay
- Replay service → Multi-lead engine: scores features
- Flask application → Live prediction: dispatches live
- Live prediction → Weather client: fetches weather
- Weather client → Open-Meteo: requests data
- Weather client → GFS NWP: requests NWP
- Live prediction → Live feature adapter: builds features
- Live feature adapter → Live feature builder: constructs vector
- Live prediction → Multi-lead engine: scores vector
- Replay service → Satellite replay context: attaches context
- INSAT-3DR evidence → Satellite replay context: supplies evidence
- Flask application → Dashboard scripts: returns results
- Dashboard scripts → Geographic map: renders locations