# davidebason/grid-stress architecture

> Architecture diagram of the GitHub repository davidebason/grid-stress, 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/davidebason/grid-stress
- Repository: https://github.com/davidebason/grid-stress

## Overview

Gridstress turns Dutch ENTSO-E price, load and generation responses into validated DuckDB tables, then analyzes when flexible electricity consumption can save money. The main workflow is fetch → parse/load → derive and validate → query analyses → report recommendations, with separate evidence and figure-generation branches. README and sampled loader/client code establish the principal handoffs; analysis and reporting details are documented at a higher level, so their internal query-to-query relationships are not inferred.

Main entry points: [`src/gridstress/load.py`](https://github.com/davidebason/grid-stress/blob/main/src/gridstress/load.py) (Transactional loader), [`src/gridstress/fetch.py`](https://github.com/davidebason/grid-stress/blob/main/src/gridstress/fetch.py) (Dataset fetcher), [`analysis/04_shifting_gain.sql`](https://github.com/davidebason/grid-stress/blob/main/analysis/04_shifting_gain.sql) (Shifting gains), [`src/gridstress/client.py`](https://github.com/davidebason/grid-stress/blob/main/src/gridstress/client.py) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data ingestion"]
  node_fetcher["Dataset fetcher<br/>[fetch.py]"]
  node_api_client["API client<br/>[client.py]"]
  node_raw_xml["Raw XML"]
  node_parser["XML parser<br/>[my_parse.py]"]
end

subgraph group_warehouse["Data modeling"]
  node_loader["Transactional loader<br/>[load.py]"]
  node_fact_schema["Fact schema<br/>[02_facts.sql]"]
  node_dimensions["Dimensions"]
  node_time_dimension["Time dimension<br/>[03_dim_time.sql]"]
  node_derived_tables["Derived tables"]
  node_post_crisis["Post-crisis tables<br/>[05_post_crisis.sql]"]
  node_price_units["Price-unit table<br/>[06_price_units.sql]"]
  node_warehouse_db[("DuckDB warehouse")]
  node_validation["Data validation<br/>[validate.py]"]
end

subgraph group_analysis["Analysis"]
  node_negative_extreme["Price extremes"]
  node_generation_mix["Generation mix"]
  node_swing_analysis["Generation swing<br/>[03_swing.sql]"]
  node_shifting_gain["Shifting gains"]
end

subgraph group_evidence["Evidence and outputs"]
  node_evidence_scripts["Evidence checks"]
  node_report["Findings and advice<br/>[REPORT.md]"]
  node_data_notes["Data provenance<br/>[DATA.md]"]
  node_figure_notebook["Figure generation"]
  node_figure["Savings figure"]
end

node_analyst(("Analyst"))
node_entsoe["ENTSO-E API"]

node_analyst -->|"starts fetch"| node_fetcher
node_fetcher -->|"requests windows"| node_api_client
node_api_client -->|"requests data"| node_entsoe
node_fetcher -->|"saves responses"| node_raw_xml
node_raw_xml -->|"supplies files"| node_loader
node_loader -->|"parses responses"| node_parser
node_loader -->|"runs schema"| node_dimensions
node_loader -->|"runs schema"| node_fact_schema
node_loader -->|"runs schema"| node_time_dimension
node_loader -->|"inserts facts"| node_warehouse_db
node_loader -->|"executes SQL"| node_derived_tables
node_loader -->|"executes SQL"| node_post_crisis
node_loader -->|"executes SQL"| node_price_units
node_loader -->|"validates transaction"| node_validation
node_validation -->|"checks tables"| node_warehouse_db
node_analyst -->|"runs query"| node_negative_extreme
node_analyst -->|"runs query"| node_generation_mix
node_analyst -->|"runs query"| node_swing_analysis
node_analyst -->|"runs query"| node_shifting_gain
node_negative_extreme -->|"queries tables"| node_warehouse_db
node_generation_mix -->|"queries tables"| node_warehouse_db
node_swing_analysis -->|"queries tables"| node_warehouse_db
node_shifting_gain -->|"queries tables"| node_warehouse_db
node_evidence_scripts -->|"regenerates figures"| node_data_notes
node_analyst -->|"reads findings"| node_report
node_figure_notebook -->|"draws figure"| node_figure
node_shifting_gain -.->|"informs recommendation"| node_report

click node_fetcher "https://github.com/davidebason/grid-stress/blob/main/src/gridstress/fetch.py"
click node_api_client "https://github.com/davidebason/grid-stress/blob/main/src/gridstress/client.py"
click node_raw_xml "https://github.com/davidebason/grid-stress/tree/main/data/raw"
click node_parser "https://github.com/davidebason/grid-stress/blob/main/src/gridstress/my_parse.py"
click node_loader "https://github.com/davidebason/grid-stress/blob/main/src/gridstress/load.py"
click node_fact_schema "https://github.com/davidebason/grid-stress/blob/main/sql/02_facts.sql"
click node_dimensions "https://github.com/davidebason/grid-stress/blob/main/sql/01_dim_production_type.sql"
click node_time_dimension "https://github.com/davidebason/grid-stress/blob/main/sql/03_dim_time.sql"
click node_derived_tables "https://github.com/davidebason/grid-stress/blob/main/sql/04_hourly_tables.sql"
click node_post_crisis "https://github.com/davidebason/grid-stress/blob/main/sql/05_post_crisis.sql"
click node_price_units "https://github.com/davidebason/grid-stress/blob/main/sql/06_price_units.sql"
click node_validation "https://github.com/davidebason/grid-stress/blob/main/src/gridstress/validate.py"
click node_negative_extreme "https://github.com/davidebason/grid-stress/blob/main/analysis/01_negative_and_extreme.sql"
click node_generation_mix "https://github.com/davidebason/grid-stress/blob/main/analysis/02_generation_mix.sql"
click node_swing_analysis "https://github.com/davidebason/grid-stress/blob/main/analysis/03_swing.sql"
click node_shifting_gain "https://github.com/davidebason/grid-stress/blob/main/analysis/04_shifting_gain.sql"
click node_evidence_scripts "https://github.com/davidebason/grid-stress/tree/main/evidence"
click node_report "https://github.com/davidebason/grid-stress/blob/main/REPORT.md"
click node_data_notes "https://github.com/davidebason/grid-stress/blob/main/DATA.md"
click node_figure_notebook "https://github.com/davidebason/grid-stress/blob/main/notebooks/image_creation.ipynb"
click node_figure "https://github.com/davidebason/grid-stress/tree/main/figures"

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_fetcher,node_api_client,node_raw_xml,node_parser toneBlue
class node_loader,node_fact_schema,node_dimensions,node_time_dimension,node_derived_tables,node_post_crisis,node_price_units,node_warehouse_db,node_validation toneAmber
class node_negative_extreme,node_generation_mix,node_swing_analysis,node_shifting_gain,node_entsoe toneMint
class node_evidence_scripts,node_report,node_data_notes,node_figure_notebook,node_figure toneRose
class node_analyst toneIndigo
```

## Components

### Data ingestion

- [Dataset fetcher](https://github.com/davidebason/grid-stress/blob/main/src/gridstress/fetch.py): `src/gridstress/fetch.py`
- [API client](https://github.com/davidebason/grid-stress/blob/main/src/gridstress/client.py): `src/gridstress/client.py`
- [Raw XML](https://github.com/davidebason/grid-stress/tree/main/data/raw): `data/raw`
- [XML parser](https://github.com/davidebason/grid-stress/blob/main/src/gridstress/my_parse.py): `src/gridstress/my_parse.py`

### Data modeling

- [Transactional loader](https://github.com/davidebason/grid-stress/blob/main/src/gridstress/load.py): `src/gridstress/load.py`
- [Fact schema](https://github.com/davidebason/grid-stress/blob/main/sql/02_facts.sql): `sql/02_facts.sql`
- [Dimensions](https://github.com/davidebason/grid-stress/blob/main/sql/01_dim_production_type.sql): `sql/01_dim_production_type.sql`
- [Time dimension](https://github.com/davidebason/grid-stress/blob/main/sql/03_dim_time.sql): `sql/03_dim_time.sql`
- [Derived tables](https://github.com/davidebason/grid-stress/blob/main/sql/04_hourly_tables.sql): `sql/04_hourly_tables.sql`
- [Post-crisis tables](https://github.com/davidebason/grid-stress/blob/main/sql/05_post_crisis.sql): `sql/05_post_crisis.sql`
- [Price-unit table](https://github.com/davidebason/grid-stress/blob/main/sql/06_price_units.sql): `sql/06_price_units.sql`
- **DuckDB warehouse**
- [Data validation](https://github.com/davidebason/grid-stress/blob/main/src/gridstress/validate.py): `src/gridstress/validate.py`

### Analysis

- [Price extremes](https://github.com/davidebason/grid-stress/blob/main/analysis/01_negative_and_extreme.sql): `analysis/01_negative_and_extreme.sql`
- [Generation mix](https://github.com/davidebason/grid-stress/blob/main/analysis/02_generation_mix.sql): `analysis/02_generation_mix.sql`
- [Generation swing](https://github.com/davidebason/grid-stress/blob/main/analysis/03_swing.sql): `analysis/03_swing.sql`
- [Shifting gains](https://github.com/davidebason/grid-stress/blob/main/analysis/04_shifting_gain.sql): `analysis/04_shifting_gain.sql`

### Evidence and outputs

- [Evidence checks](https://github.com/davidebason/grid-stress/tree/main/evidence): `evidence`
- [Findings and advice](https://github.com/davidebason/grid-stress/blob/main/REPORT.md): `REPORT.md`
- [Data provenance](https://github.com/davidebason/grid-stress/blob/main/DATA.md): `DATA.md`
- [Figure generation](https://github.com/davidebason/grid-stress/blob/main/notebooks/image_creation.ipynb): `notebooks/image_creation.ipynb`
- [Savings figure](https://github.com/davidebason/grid-stress/tree/main/figures): `figures`

### Other components

- **Analyst**
- **ENTSO-E API**

## Connections

- Analyst → Dataset fetcher: starts fetch (evidence: `README.md`)
- Dataset fetcher → API client: requests windows (evidence: `src/gridstress/fetch.py`)
- API client → ENTSO-E API: requests data (evidence: `README.md`)
- Dataset fetcher → Raw XML: saves responses (evidence: `src/gridstress/fetch.py`)
- Raw XML → Transactional loader: supplies files (evidence: `src/gridstress/load.py`)
- Transactional loader → XML parser: parses responses (evidence: `src/gridstress/load.py`)
- Transactional loader → Dimensions: runs schema (evidence: `src/gridstress/load.py`)
- Transactional loader → Fact schema: runs schema (evidence: `src/gridstress/load.py`)
- Transactional loader → Time dimension: runs schema (evidence: `src/gridstress/load.py`)
- Transactional loader → DuckDB warehouse: inserts facts (evidence: `src/gridstress/load.py`)
- Transactional loader → Derived tables: executes SQL (evidence: `src/gridstress/load.py`)
- Transactional loader → Post-crisis tables: executes SQL (evidence: `src/gridstress/load.py`)
- Transactional loader → Price-unit table: executes SQL (evidence: `src/gridstress/load.py`)
- Transactional loader → Data validation: validates transaction (evidence: `src/gridstress/load.py`)
- Data validation → DuckDB warehouse: checks tables (evidence: `src/gridstress/validate.py`)
- Analyst → Price extremes: runs query (evidence: `README.md`)
- Analyst → Generation mix: runs query (evidence: `README.md`)
- Analyst → Generation swing: runs query (evidence: `README.md`)
- Analyst → Shifting gains: runs query (evidence: `README.md`)
- Price extremes → DuckDB warehouse: queries tables (evidence: `README.md`)
- Generation mix → DuckDB warehouse: queries tables (evidence: `README.md`)
- Generation swing → DuckDB warehouse: queries tables (evidence: `README.md`)
- Shifting gains → DuckDB warehouse: queries tables (evidence: `README.md`)
- Evidence checks → Data provenance: regenerates figures (evidence: `README.md`)
- Analyst → Findings and advice: reads findings (evidence: `README.md`)
- Figure generation → Savings figure: draws figure (evidence: `README.md`)
- Shifting gains → Findings and advice: informs recommendation
