# shreyas30016/forecast-forge architecture

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

- Interactive diagram: https://gitdiagram.com/shreyas30016/forecast-forge
- Repository: https://github.com/shreyas30016/forecast-forge

## Overview

Forecast Forge AI turns multi-model weather forecasts into adaptive, uncertainty-aware guidance with evaluation and decision provenance. The main path runs from the dashboard through the API and forecast orchestrator to provider data and ensemble results. Separate capabilities cover historical skill evaluation, spatial guidance, extremes, bust detection, probabilistic forecasts, replay, and the trace-grounded copilot. README claims guide the unsampled feature links; sampled code confirms the orchestrator, ensemble engine, replay trace writes, and trace storage behavior.

Main entry points: [`forecast_forge/api/app.py`](https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/api/app.py) (FastAPI app), [`forecast_forge/replay/service.py`](https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/replay/service.py) (Scientific replay), [`forecast_forge/agent/runtime.py`](https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/agent/runtime.py) (Nemotron runtime), [`ui/src/app/page.tsx`](https://github.com/shreyas30016/forecast-forge/blob/main/ui/src/app/page.tsx) (Dashboard UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_dashboard["Dashboard UI<br/>[page.tsx]"]
end

subgraph group_api["API surface"]
  node_api_app["FastAPI app<br/>[app.py]"]
  node_forecast_route["Forecast route<br/>[forecast.py]"]
  node_ensemble_route["Ensemble route<br/>[ensemble.py]"]
  node_evaluation_route["Evaluation route<br/>[evaluation.py]"]
  node_replay_route["Replay route<br/>[replay.py]"]
  node_agent_route["Copilot route<br/>[agent_router.py]"]
end

subgraph group_forecast["Forecast and data"]
  node_orchestrator["Forecast orchestrator<br/>[service.py]"]
  node_providers["NWP adapters<br/>[ifs.py]"]
  node_ensemble_engine["Ensemble engine<br/>[engine.py]"]
  node_validation["Forecast validation<br/>[validator.py]"]
  node_spatial["Spatial grid service<br/>[grid_service.py]"]
end

subgraph group_intelligence["Evaluation and intelligence"]
  node_historical["Historical alignment<br/>[alignment.py]"]
  node_evaluation["Skill evaluation<br/>[scoring.py]"]
  node_probabilistic["Probabilistic guidance<br/>[ensemble.py]"]
  node_extremes["Extreme detection<br/>[service.py]"]
  node_bust["Bust detection<br/>[service.py]"]
  node_replay["Scientific replay<br/>[service.py]"]
  node_trace_builder["Trace builder<br/>[builder.py]"]
  node_trace_storage[("Trace storage<br/>[storage.py]")]
  node_copilot["Nemotron runtime<br/>[runtime.py]"]
end

node_user(("Forecaster"))
node_open_meteo["Open-Meteo"]
node_era5[("ERA5 reference")]
node_nemotron["Nemotron service"]

node_user -->|"uses"| node_dashboard
node_dashboard -->|"sends requests"| node_api_app
node_api_app -->|"dispatches"| node_forecast_route
node_api_app -->|"dispatches"| node_ensemble_route
node_api_app -->|"dispatches"| node_evaluation_route
node_api_app -->|"dispatches"| node_replay_route
node_api_app -->|"dispatches"| node_agent_route
node_forecast_route -->|"requests forecasts"| node_orchestrator
node_orchestrator -->|"fetches concurrently"| node_providers
node_providers -->|"queries"| node_open_meteo
node_ensemble_route -->|"generates blend"| node_ensemble_engine
node_ensemble_engine -.->|"validates output"| node_validation
node_evaluation_route -->|"requests scoring"| node_evaluation
node_evaluation -->|"uses aligned data"| node_historical
node_historical -->|"loads reference"| node_era5
node_spatial -->|"fetches grid data"| node_open_meteo
node_extremes -->|"requests probabilities"| node_probabilistic
node_bust -->|"requests forecast"| node_probabilistic
node_replay_route -->|"requests timeline"| node_replay
node_replay -->|"builds traces"| node_trace_builder
node_replay -->|"saves traces"| node_trace_storage
node_agent_route -->|"invokes"| node_copilot
node_copilot -->|"retrieves trace context"| node_trace_storage
node_copilot -.->|"queries"| node_nemotron

click node_dashboard "https://github.com/shreyas30016/forecast-forge/blob/main/ui/src/app/page.tsx"
click node_api_app "https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/api/app.py"
click node_forecast_route "https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/api/routes/forecast.py"
click node_ensemble_route "https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/api/routes/ensemble.py"
click node_evaluation_route "https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/api/routes/evaluation.py"
click node_replay_route "https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/api/routes/replay.py"
click node_agent_route "https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/api/agent_router.py"
click node_orchestrator "https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/orchestrator/service.py"
click node_providers "https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/providers/open_meteo/ifs.py"
click node_ensemble_engine "https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/ensemble/engine.py"
click node_validation "https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/validation/validator.py"
click node_historical "https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/historical/alignment.py"
click node_evaluation "https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/evaluation/scoring.py"
click node_spatial "https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/spatial/grid_service.py"
click node_probabilistic "https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/providers/open_meteo/ensemble.py"
click node_extremes "https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/extremes/service.py"
click node_bust "https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/evaluation/bust/service.py"
click node_replay "https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/replay/service.py"
click node_trace_builder "https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/trace/builder.py"
click node_trace_storage "https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/trace/storage.py"
click node_copilot "https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/agent/runtime.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_app,node_forecast_route,node_ensemble_route,node_evaluation_route,node_replay_route,node_agent_route,node_era5 toneAmber
class node_orchestrator,node_providers,node_ensemble_engine,node_validation,node_spatial toneMint
class node_historical,node_evaluation,node_probabilistic,node_extremes,node_bust,node_replay,node_trace_builder,node_trace_storage,node_copilot toneRose
class node_user,node_open_meteo,node_nemotron toneIndigo
```

## Components

### User interface

- [Dashboard UI](https://github.com/shreyas30016/forecast-forge/blob/main/ui/src/app/page.tsx): `ui/src/app/page.tsx`

### API surface

- [FastAPI app](https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/api/app.py): `forecast_forge/api/app.py`
- [Forecast route](https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/api/routes/forecast.py): `forecast_forge/api/routes/forecast.py`
- [Ensemble route](https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/api/routes/ensemble.py): `forecast_forge/api/routes/ensemble.py`
- [Evaluation route](https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/api/routes/evaluation.py): `forecast_forge/api/routes/evaluation.py`
- [Replay route](https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/api/routes/replay.py): `forecast_forge/api/routes/replay.py`
- [Copilot route](https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/api/agent_router.py): `forecast_forge/api/agent_router.py`

### Forecast and data

- [Forecast orchestrator](https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/orchestrator/service.py): `forecast_forge/orchestrator/service.py`
- [NWP adapters](https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/providers/open_meteo/ifs.py): `forecast_forge/providers/open_meteo/ifs.py`
- [Ensemble engine](https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/ensemble/engine.py): `forecast_forge/ensemble/engine.py`
- [Forecast validation](https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/validation/validator.py): `forecast_forge/validation/validator.py`
- [Spatial grid service](https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/spatial/grid_service.py): `forecast_forge/spatial/grid_service.py`

### Evaluation and intelligence

- [Historical alignment](https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/historical/alignment.py): `forecast_forge/historical/alignment.py`
- [Skill evaluation](https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/evaluation/scoring.py): `forecast_forge/evaluation/scoring.py`
- [Probabilistic guidance](https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/providers/open_meteo/ensemble.py): `forecast_forge/providers/open_meteo/ensemble.py`
- [Extreme detection](https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/extremes/service.py): `forecast_forge/extremes/service.py`
- [Bust detection](https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/evaluation/bust/service.py): `forecast_forge/evaluation/bust/service.py`
- [Scientific replay](https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/replay/service.py): `forecast_forge/replay/service.py`
- [Trace builder](https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/trace/builder.py): `forecast_forge/trace/builder.py`
- [Trace storage](https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/trace/storage.py): `forecast_forge/trace/storage.py`
- [Nemotron runtime](https://github.com/shreyas30016/forecast-forge/blob/main/forecast_forge/agent/runtime.py): `forecast_forge/agent/runtime.py`

### Other components

- **Forecaster**
- **Open-Meteo**
- **ERA5 reference**
- **Nemotron service**

## Connections

- Forecaster → Dashboard UI: uses
- Dashboard UI → FastAPI app: sends requests
- FastAPI app → Forecast route: dispatches
- FastAPI app → Ensemble route: dispatches
- FastAPI app → Evaluation route: dispatches
- FastAPI app → Replay route: dispatches
- FastAPI app → Copilot route: dispatches
- Forecast route → Forecast orchestrator: requests forecasts
- Forecast orchestrator → NWP adapters: fetches concurrently
- NWP adapters → Open-Meteo: queries
- Ensemble route → Ensemble engine: generates blend
- Ensemble engine → Forecast validation: validates output
- Evaluation route → Skill evaluation: requests scoring
- Skill evaluation → Historical alignment: uses aligned data
- Historical alignment → ERA5 reference: loads reference
- Spatial grid service → Open-Meteo: fetches grid data
- Extreme detection → Probabilistic guidance: requests probabilities
- Bust detection → Probabilistic guidance: requests forecast
- Replay route → Scientific replay: requests timeline
- Scientific replay → Trace builder: builds traces
- Scientific replay → Trace storage: saves traces
- Copilot route → Nemotron runtime: invokes
- Nemotron runtime → Trace storage: retrieves trace context
- Nemotron runtime → Nemotron service: queries