# baitc-hacks/hack-17c230f8-ctrlx architecture

> Architecture diagram of the GitHub repository baitc-hacks/hack-17c230f8-ctrlx, 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/baitc-hacks/hack-17c230f8-ctrlx
- Repository: https://github.com/baitc-hacks/hack-17c230f8-ctrlx

## Overview

WindCast produces 48-hour wind-farm generation forecasts, uncertainty bands, dispatcher summaries and day-ahead bid data. The main workflow runs from CLI or API through the forecast service and deterministic agent: select an issue, obtain and validate historical weather, prepare turbine data, model and check output, optionally recompute with fresher weather, then publish artifacts for the API and web interface. The README documents evaluation, agent evidence, user question-answering and IT integration capabilities as additional branches. Some subsystem wiring is based on README documentation because sampled source excerpts are incomplete.

Main entry points: [`app/agent/orchestrator.py`](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/agent/orchestrator.py) (Agent orchestrator), [`web/lib/api.ts`](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/web/lib/api.ts) (Web API client), [`app/api/routes.py`](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/api/routes.py) (FastAPI routes), [`app/ask.py`](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/ask.py) (Ask the agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["CLI<br/>[cli.py]"]
  node_service["Forecast service<br/>[service.py]"]
end

subgraph group_agent["Forecast agent"]
  node_orchestrator["Agent orchestrator<br/>[orchestrator.py]"]
  node_planner["Run planning<br/>[planner.py]"]
  node_tools["Weather tools<br/>[tools.py]"]
  node_forecast_store[("Forecast artifacts")]
  node_agent_log["Agent run journal<br/>[log.py]"]
end

subgraph group_data["Data and evaluation"]
  node_weather["Weather archive<br/>[weather.py]"]
  node_cache[("Weather cache")]
  node_turbine["Turbine history<br/>[data.py]"]
  node_features["Forecast features<br/>[features.py]"]
  node_models["Generation models<br/>[models.py]"]
  node_evaluation["Metrics and replay<br/>[evaluate.py]"]
end

subgraph group_serving["Serving and UI"]
  node_web["Web platform<br/>[page.tsx]"]
  node_api["FastAPI routes<br/>[routes.py]"]
  node_ask["Ask the agent<br/>[ask.py]"]
  node_web_api["Web API client<br/>[api.ts]"]
  node_bid["Bid worksheet<br/>[page.tsx]"]
  node_agent_page["Agent journal view<br/>[page.tsx]"]
  node_quality["Quality dashboard<br/>[page.tsx]"]
  node_integration["IT integration view<br/>[page.tsx]"]
end

subgraph group_integrations["External services"]
  node_llm["LLM summary<br/>[llm.py]"]
  node_open_meteo["Open-Meteo"]
end

node_dispatcher(("Wind-farm dispatcher"))

node_dispatcher -->|"views forecasts"| node_web
node_dispatcher -->|"runs backtests"| node_cli
node_cli -->|"requests forecasts"| node_service
node_web -->|"requests data"| node_web_api
node_web_api -->|"calls API"| node_api
node_api -->|"runs forecast"| node_service
node_service -->|"runs issue"| node_orchestrator
node_orchestrator -->|"plans run"| node_planner
node_orchestrator -->|"fetches weather"| node_tools
node_tools -->|"reads archive"| node_weather
node_weather -->|"reads and writes"| node_cache
node_weather -.->|"fetches runs"| node_open_meteo
node_orchestrator -->|"loads history"| node_turbine
node_orchestrator -->|"prepares inputs"| node_features
node_orchestrator -->|"runs model"| node_models
node_orchestrator -->|"publishes issues"| node_forecast_store
node_orchestrator -->|"records steps"| node_agent_log
node_cli -->|"runs evaluation"| node_evaluation
node_api -->|"reads issues and metrics"| node_forecast_store
node_api -->|"reads run log"| node_agent_log
node_api -->|"answers questions"| node_ask
node_ask -->|"reads journal"| node_agent_log
node_ask -->|"reads issue facts"| node_forecast_store
node_ask -.->|"requests summary"| node_llm
node_agent_page -->|"loads run logs"| node_web_api
node_bid -->|"loads issue data"| node_web_api
node_quality -->|"loads metrics"| node_web_api
node_integration -->|"checks service"| node_web_api

click node_cli "https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/cli.py"
click node_web "https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/web/app/page.tsx"
click node_api "https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/api/routes.py"
click node_service "https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/service.py"
click node_orchestrator "https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/agent/orchestrator.py"
click node_planner "https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/agent/planner.py"
click node_tools "https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/agent/tools.py"
click node_weather "https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/weather.py"
click node_turbine "https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/data.py"
click node_features "https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/features.py"
click node_models "https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/models.py"
click node_evaluation "https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/evaluate.py"
click node_agent_log "https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/agent/log.py"
click node_ask "https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/ask.py"
click node_llm "https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/llm.py"
click node_web_api "https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/web/lib/api.ts"
click node_bid "https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/web/app/bid/page.tsx"
click node_agent_page "https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/web/app/agent/page.tsx"
click node_quality "https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/web/app/quality/page.tsx"
click node_integration "https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/web/app/integration/page.tsx"

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_cli,node_service toneBlue
class node_orchestrator,node_planner,node_tools,node_forecast_store,node_agent_log toneAmber
class node_weather,node_cache,node_turbine,node_features,node_models,node_evaluation toneMint
class node_web,node_api,node_ask,node_web_api,node_bid,node_agent_page,node_quality,node_integration toneRose
class node_llm,node_open_meteo,node_dispatcher toneIndigo
```

## Components

### Entry points

- [CLI](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/cli.py): `app/cli.py`
- [Forecast service](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/service.py): `app/service.py`

### Forecast agent

- [Agent orchestrator](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/agent/orchestrator.py): `app/agent/orchestrator.py`
- [Run planning](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/agent/planner.py): `app/agent/planner.py`
- [Weather tools](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/agent/tools.py): `app/agent/tools.py`
- **Forecast artifacts**
- [Agent run journal](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/agent/log.py): `app/agent/log.py`

### Data and evaluation

- [Weather archive](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/weather.py): `app/weather.py`
- **Weather cache**
- [Turbine history](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/data.py): `app/data.py`
- [Forecast features](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/features.py): `app/features.py`
- [Generation models](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/models.py): `app/models.py`
- [Metrics and replay](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/evaluate.py): `app/evaluate.py`

### Serving and UI

- [Web platform](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/web/app/page.tsx): `web/app/page.tsx`
- [FastAPI routes](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/api/routes.py): `app/api/routes.py`
- [Ask the agent](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/ask.py): `app/ask.py`
- [Web API client](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/web/lib/api.ts): `web/lib/api.ts`
- [Bid worksheet](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/web/app/bid/page.tsx): `web/app/bid/page.tsx`
- [Agent journal view](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/web/app/agent/page.tsx): `web/app/agent/page.tsx`
- [Quality dashboard](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/web/app/quality/page.tsx): `web/app/quality/page.tsx`
- [IT integration view](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/web/app/integration/page.tsx): `web/app/integration/page.tsx`

### External services

- [LLM summary](https://github.com/baitc-hacks/hack-17c230f8-ctrlx/blob/main/app/llm.py): `app/llm.py`
- **Open-Meteo**

### Other components

- **Wind-farm dispatcher**

## Connections

- Wind-farm dispatcher → Web platform: views forecasts
- Wind-farm dispatcher → CLI: runs backtests
- CLI → Forecast service: requests forecasts
- Web platform → Web API client: requests data
- Web API client → FastAPI routes: calls API
- FastAPI routes → Forecast service: runs forecast
- Forecast service → Agent orchestrator: runs issue
- Agent orchestrator → Run planning: plans run
- Agent orchestrator → Weather tools: fetches weather
- Weather tools → Weather archive: reads archive
- Weather archive → Weather cache: reads and writes
- Weather archive → Open-Meteo: fetches runs
- Agent orchestrator → Turbine history: loads history
- Agent orchestrator → Forecast features: prepares inputs
- Agent orchestrator → Generation models: runs model
- Agent orchestrator → Forecast artifacts: publishes issues
- Agent orchestrator → Agent run journal: records steps
- CLI → Metrics and replay: runs evaluation
- FastAPI routes → Forecast artifacts: reads issues and metrics
- FastAPI routes → Agent run journal: reads run log
- FastAPI routes → Ask the agent: answers questions
- Ask the agent → Agent run journal: reads journal
- Ask the agent → Forecast artifacts: reads issue facts
- Ask the agent → LLM summary: requests summary
- Agent journal view → Web API client: loads run logs
- Bid worksheet → Web API client: loads issue data
- Quality dashboard → Web API client: loads metrics
- IT integration view → Web API client: checks service