# letsbegincode/european-power-fair-value-forecasting architecture

> Architecture diagram of the GitHub repository letsbegincode/european-power-fair-value-forecasting, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/letsbegincode/european-power-fair-value-forecasting
- Repository: https://github.com/letsbegincode/european-power-fair-value-forecasting

## Overview

Powerfair is a DE-LU Day-Ahead power fair-value forecasting pipeline. A command-line run loads configuration, fetches and normalizes public market data, assesses data quality, engineers forecasting features, trains and validates models, translates forecasts into prompt baseload/peak values, and writes desk-facing reports. The graph preserves the documented AI-assisted QA branch and model validation capabilities. Some subsystem links are documented only in the README; those edges cite it rather than implying unsampled calls were inspected.

Main entry points: [`src/powerfair/cli.py`](https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/cli.py) (Pipeline CLI), [`src/powerfair/validation/qa.py`](https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/validation/qa.py) (Deterministic QA), [`src/powerfair/data/sources.py`](https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/data/sources.py) (Public data ingestion), [`src/powerfair/forecasting/modeling.py`](https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/forecasting/modeling.py) (Model validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Run orchestration"]
  node_cli["Pipeline CLI<br/>[cli.py]"]
end

subgraph group_data["Market data"]
  node_config["Run configuration<br/>[config.py]"]
  node_ingestion["Public data ingestion<br/>[sources.py]"]
  node_public_data{{"Energy-Charts API"}}
  node_hourly_data["Hourly market data"]
  node_time["UTC and DST utilities<br/>[time_utils.py]"]
end

subgraph group_quality["Quality assurance"]
  node_qa["Deterministic QA<br/>[qa.py]"]
  node_ai_qa["Guarded AI QA<br/>[qa_rules.py]"]
  node_llm{{"LLM provider"}}
  node_qa_outputs["QA reports"]
end

subgraph group_forecast["Forecast and desk outputs"]
  node_features["Feature engineering<br/>[features.py]"]
  node_feature_data["Feature table<br/>[de_lu_features.csv]"]
  node_modeling["Model validation<br/>[modeling.py]"]
  node_model_outputs["Forecast artifacts"]
  node_curve["Prompt curve view<br/>[curve.py]"]
  node_curve_outputs["Curve fair values"]
  node_writers["Desk and project reports<br/>[writers.py]"]
  node_reports["Trader-facing reports"]
end

node_user(("Analyst"))

node_user -->|"runs"| node_cli
node_cli -->|"loads config"| node_config
node_cli -->|"fetches data"| node_ingestion
node_ingestion -->|"requests data"| node_public_data
node_ingestion -->|"normalizes and caches"| node_hourly_data
node_cli -->|"writes processed data"| node_hourly_data
node_cli -->|"runs checks"| node_qa
node_qa -->|"checks DST"| node_time
node_qa -->|"invokes"| node_ai_qa
node_ai_qa -.->|"requests rule proposals"| node_llm
node_qa -->|"writes reports"| node_qa_outputs
node_cli -->|"builds features"| node_features
node_features -->|"adds time fields"| node_time
node_cli -->|"writes features"| node_feature_data
node_cli -->|"trains and validates"| node_modeling
node_modeling -->|"selects feature columns"| node_features
node_modeling -->|"writes forecast artifacts"| node_model_outputs
node_cli -->|"builds curve view"| node_curve
node_curve -->|"writes fair values"| node_curve_outputs
node_cli -->|"writes reports"| node_writers
node_writers -->|"generates desk notes"| node_reports

click node_cli "https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/cli.py"
click node_config "https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/data/config.py"
click node_ingestion "https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/data/sources.py"
click node_hourly_data "https://github.com/letsbegincode/european-power-fair-value-forecasting/tree/main/data/processed"
click node_time "https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/data/time_utils.py"
click node_qa "https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/validation/qa.py"
click node_ai_qa "https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/ai/qa_rules.py"
click node_qa_outputs "https://github.com/letsbegincode/european-power-fair-value-forecasting/tree/main/outputs/qa"
click node_features "https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/forecasting/features.py"
click node_feature_data "https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/data/processed/de_lu_features.csv"
click node_modeling "https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/forecasting/modeling.py"
click node_model_outputs "https://github.com/letsbegincode/european-power-fair-value-forecasting/tree/main/outputs/model"
click node_curve "https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/trading/curve.py"
click node_curve_outputs "https://github.com/letsbegincode/european-power-fair-value-forecasting/tree/main/outputs/curve"
click node_writers "https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/reports/writers.py"
click node_reports "https://github.com/letsbegincode/european-power-fair-value-forecasting/tree/main/reports"

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 toneBlue
class node_config,node_ingestion,node_public_data,node_hourly_data,node_time toneAmber
class node_qa,node_ai_qa,node_llm,node_qa_outputs toneMint
class node_features,node_feature_data,node_modeling,node_model_outputs,node_curve,node_curve_outputs,node_writers,node_reports toneRose
class node_user toneIndigo
```

## Components

### Run orchestration

- [Pipeline CLI](https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/cli.py): `src/powerfair/cli.py`

### Market data

- [Run configuration](https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/data/config.py): `src/powerfair/data/config.py`
- [Public data ingestion](https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/data/sources.py): `src/powerfair/data/sources.py`
- **Energy-Charts API**
- [Hourly market data](https://github.com/letsbegincode/european-power-fair-value-forecasting/tree/main/data/processed): `data/processed`
- [UTC and DST utilities](https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/data/time_utils.py): `src/powerfair/data/time_utils.py`

### Quality assurance

- [Deterministic QA](https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/validation/qa.py): `src/powerfair/validation/qa.py`
- [Guarded AI QA](https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/ai/qa_rules.py): `src/powerfair/ai/qa_rules.py`
- **LLM provider**
- [QA reports](https://github.com/letsbegincode/european-power-fair-value-forecasting/tree/main/outputs/qa): `outputs/qa`

### Forecast and desk outputs

- [Feature engineering](https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/forecasting/features.py): `src/powerfair/forecasting/features.py`
- [Feature table](https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/data/processed/de_lu_features.csv): `data/processed/de_lu_features.csv`
- [Model validation](https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/forecasting/modeling.py): `src/powerfair/forecasting/modeling.py`
- [Forecast artifacts](https://github.com/letsbegincode/european-power-fair-value-forecasting/tree/main/outputs/model): `outputs/model`
- [Prompt curve view](https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/trading/curve.py): `src/powerfair/trading/curve.py`
- [Curve fair values](https://github.com/letsbegincode/european-power-fair-value-forecasting/tree/main/outputs/curve): `outputs/curve`
- [Desk and project reports](https://github.com/letsbegincode/european-power-fair-value-forecasting/blob/main/src/powerfair/reports/writers.py): `src/powerfair/reports/writers.py`
- [Trader-facing reports](https://github.com/letsbegincode/european-power-fair-value-forecasting/tree/main/reports): `reports`

### Other components

- **Analyst**

## Connections

- Analyst → Pipeline CLI: runs (evidence: `README.md`)
- Pipeline CLI → Run configuration: loads config (evidence: `src/powerfair/cli.py`)
- Pipeline CLI → Public data ingestion: fetches data (evidence: `src/powerfair/cli.py`)
- Public data ingestion → Energy-Charts API: requests data (evidence: `src/powerfair/data/sources.py`)
- Public data ingestion → Hourly market data: normalizes and caches (evidence: `src/powerfair/data/sources.py`)
- Pipeline CLI → Hourly market data: writes processed data (evidence: `src/powerfair/cli.py`)
- Pipeline CLI → Deterministic QA: runs checks (evidence: `src/powerfair/cli.py`)
- Deterministic QA → UTC and DST utilities: checks DST (evidence: `src/powerfair/validation/qa.py`)
- Deterministic QA → Guarded AI QA: invokes (evidence: `src/powerfair/validation/qa.py`)
- Guarded AI QA → LLM provider: requests rule proposals (evidence: `src/powerfair/ai/qa_rules.py`)
- Deterministic QA → QA reports: writes reports (evidence: `src/powerfair/validation/qa.py`)
- Pipeline CLI → Feature engineering: builds features (evidence: `src/powerfair/cli.py`)
- Feature engineering → UTC and DST utilities: adds time fields (evidence: `src/powerfair/forecasting/features.py`)
- Pipeline CLI → Feature table: writes features (evidence: `src/powerfair/cli.py`)
- Pipeline CLI → Model validation: trains and validates (evidence: `src/powerfair/cli.py`)
- Model validation → Feature engineering: selects feature columns (evidence: `src/powerfair/forecasting/modeling.py`)
- Model validation → Forecast artifacts: writes forecast artifacts (evidence: `README.md`)
- Pipeline CLI → Prompt curve view: builds curve view (evidence: `src/powerfair/cli.py`)
- Prompt curve view → Curve fair values: writes fair values (evidence: `src/powerfair/trading/curve.py`)
- Pipeline CLI → Desk and project reports: writes reports (evidence: `src/powerfair/cli.py`)
- Desk and project reports → Trader-facing reports: generates desk notes (evidence: `README.md`)
