# tuhama/stromblick architecture

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

- Interactive diagram: https://gitdiagram.com/tuhama/stromblick
- Repository: https://github.com/tuhama/stromblick

## Overview

Stromblick is a Germany electricity-market dashboard. Its principal workflow is SMARD data ingestion into Postgres, API retrieval and aggregation, then browser presentation; the product also exposes overview, tomorrow, explorer, and explain pages. The excerpts establish the ingest and API wiring plus application entry points; the README documents deployment and one-way data flow. Some page implementations and their API-query wiring were not sampled, so those links are omitted where source evidence is unavailable.

Main entry points: [`apps/api/src/app.ts`](https://github.com/tuhama/stromblick/blob/main/apps/api/src/app.ts) (API service), [`apps/web/src/routes/routes.tsx`](https://github.com/tuhama/stromblick/blob/main/apps/web/src/routes/routes.tsx) (Page routing), [`apps/api/src/ingest/run.ts`](https://github.com/tuhama/stromblick/blob/main/apps/api/src/ingest/run.ts) (Ingest runner), [`apps/api/src/routes/series.ts`](https://github.com/tuhama/stromblick/blob/main/apps/api/src/routes/series.ts) (Series routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data ingestion"]
  node_ingest_job["Ingest runner<br/>[run.ts]"]
  node_smard_client["SMARD client<br/>[client.ts]"]
  node_catalog["Series catalog<br/>[catalog.ts]"]
end

subgraph group_api["Market API"]
  node_api_service["API service<br/>[app.ts]"]
  node_ingest_route["Ingest endpoint<br/>[ingest.ts]"]
  node_database[("Postgres<br/>[db.ts]")]
  node_series_routes["Series routes<br/>[series.ts]"]
  node_readings["Readings loader<br/>[load-readings.ts]"]
  node_status_route["Status route<br/>[status.ts]"]
  node_status_loader["Ingest status<br/>[load-status.ts]"]
  node_health_route["Health route<br/>[health.ts]"]
end

subgraph group_web["Web dashboard"]
  node_web_entry["Browser app<br/>[main.tsx]"]
  node_routes["Page routing<br/>[routes.tsx]"]
  node_overview["Market overview<br/>[OverviewPage.tsx]"]
  node_generation["Generation analysis<br/>[generation.ts]"]
  node_charts["Chart rendering<br/>[DataTable.tsx]"]
  node_tomorrow["Tomorrow prices<br/>[TomorrowPage.tsx]"]
  node_explorer["Series explorer<br/>[ExplorerPage.tsx]"]
  node_explain["Data explanations<br/>[ExplainPage.tsx]"]
  node_query_client["Query management<br/>[query-client.ts]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_shared["Shared contracts"]
  node_contracts["Data contracts<br/>[readings.ts]"]
end

node_smard[("SMARD data")]
node_browser(("Dashboard user"))

node_smard -->|"serves data"| node_smard_client
node_ingest_route -->|"starts job"| node_ingest_job
node_ingest_job -->|"fetches weeks"| node_smard_client
node_ingest_job -->|"ingests series"| node_catalog
node_ingest_job -->|"upserts readings"| node_database
node_api_service -->|"mounts route"| node_ingest_route
node_api_service -->|"mounts route"| node_series_routes
node_api_service -->|"mounts route"| node_status_route
node_api_service -->|"mounts route"| node_health_route
node_series_routes -->|"loads series"| node_readings
node_readings -->|"queries readings"| node_database
node_series_routes -->|"uses catalog"| node_catalog
node_status_route -->|"loads status"| node_status_loader
node_status_loader -->|"reads runs"| node_database
node_browser -->|"opens dashboard"| node_web_entry
node_web_entry -->|"starts router"| node_routes
node_routes -->|"routes to page"| node_overview
node_routes -->|"routes to page"| node_tomorrow
node_routes -->|"routes to page"| node_explorer
node_routes -->|"routes to page"| node_explain
node_web_entry -->|"provides queries"| node_query_client
node_overview -->|"uses analysis"| node_generation
node_generation -->|"builds table data"| node_charts
node_query_client -->|"uses requests"| node_api_client
node_api_service -->|"shares schemas"| node_contracts
node_api_client -->|"validates responses"| node_contracts

click node_api_service "https://github.com/tuhama/stromblick/blob/main/apps/api/src/app.ts"
click node_ingest_route "https://github.com/tuhama/stromblick/blob/main/apps/api/src/routes/ingest.ts"
click node_ingest_job "https://github.com/tuhama/stromblick/blob/main/apps/api/src/ingest/run.ts"
click node_smard_client "https://github.com/tuhama/stromblick/blob/main/apps/api/src/smard/client.ts"
click node_catalog "https://github.com/tuhama/stromblick/blob/main/apps/api/src/smard/catalog.ts"
click node_database "https://github.com/tuhama/stromblick/blob/main/apps/api/src/db.ts"
click node_series_routes "https://github.com/tuhama/stromblick/blob/main/apps/api/src/routes/series.ts"
click node_readings "https://github.com/tuhama/stromblick/blob/main/apps/api/src/series/load-readings.ts"
click node_status_route "https://github.com/tuhama/stromblick/blob/main/apps/api/src/routes/status.ts"
click node_status_loader "https://github.com/tuhama/stromblick/blob/main/apps/api/src/status/load-status.ts"
click node_health_route "https://github.com/tuhama/stromblick/blob/main/apps/api/src/routes/health.ts"
click node_web_entry "https://github.com/tuhama/stromblick/blob/main/apps/web/src/main.tsx"
click node_routes "https://github.com/tuhama/stromblick/blob/main/apps/web/src/routes/routes.tsx"
click node_overview "https://github.com/tuhama/stromblick/blob/main/apps/web/src/features/overview/OverviewPage.tsx"
click node_generation "https://github.com/tuhama/stromblick/blob/main/apps/web/src/features/overview/generation.ts"
click node_charts "https://github.com/tuhama/stromblick/blob/main/apps/web/src/charts/DataTable.tsx"
click node_tomorrow "https://github.com/tuhama/stromblick/blob/main/apps/web/src/features/tomorrow/TomorrowPage.tsx"
click node_explorer "https://github.com/tuhama/stromblick/blob/main/apps/web/src/features/explorer/ExplorerPage.tsx"
click node_explain "https://github.com/tuhama/stromblick/blob/main/apps/web/src/features/explain/ExplainPage.tsx"
click node_query_client "https://github.com/tuhama/stromblick/blob/main/apps/web/src/api/query-client.ts"
click node_api_client "https://github.com/tuhama/stromblick/blob/main/apps/web/src/api/client.ts"
click node_contracts "https://github.com/tuhama/stromblick/blob/main/packages/shared/src/readings.ts"

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_ingest_job,node_smard_client,node_catalog,node_browser toneBlue
class node_api_service,node_ingest_route,node_database,node_series_routes,node_readings,node_status_route,node_status_loader,node_health_route,node_smard toneAmber
class node_web_entry,node_routes,node_overview,node_generation,node_charts,node_tomorrow,node_explorer,node_explain,node_query_client,node_api_client toneMint
class node_contracts toneRose
```

## Components

### Data ingestion

- [Ingest runner](https://github.com/tuhama/stromblick/blob/main/apps/api/src/ingest/run.ts): `apps/api/src/ingest/run.ts`
- [SMARD client](https://github.com/tuhama/stromblick/blob/main/apps/api/src/smard/client.ts): `apps/api/src/smard/client.ts`
- [Series catalog](https://github.com/tuhama/stromblick/blob/main/apps/api/src/smard/catalog.ts): `apps/api/src/smard/catalog.ts`

### Market API

- [API service](https://github.com/tuhama/stromblick/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Ingest endpoint](https://github.com/tuhama/stromblick/blob/main/apps/api/src/routes/ingest.ts): `apps/api/src/routes/ingest.ts`
- [Postgres](https://github.com/tuhama/stromblick/blob/main/apps/api/src/db.ts): `apps/api/src/db.ts`
- [Series routes](https://github.com/tuhama/stromblick/blob/main/apps/api/src/routes/series.ts): `apps/api/src/routes/series.ts`
- [Readings loader](https://github.com/tuhama/stromblick/blob/main/apps/api/src/series/load-readings.ts): `apps/api/src/series/load-readings.ts`
- [Status route](https://github.com/tuhama/stromblick/blob/main/apps/api/src/routes/status.ts): `apps/api/src/routes/status.ts`
- [Ingest status](https://github.com/tuhama/stromblick/blob/main/apps/api/src/status/load-status.ts): `apps/api/src/status/load-status.ts`
- [Health route](https://github.com/tuhama/stromblick/blob/main/apps/api/src/routes/health.ts): `apps/api/src/routes/health.ts`

### Web dashboard

- [Browser app](https://github.com/tuhama/stromblick/blob/main/apps/web/src/main.tsx): `apps/web/src/main.tsx`
- [Page routing](https://github.com/tuhama/stromblick/blob/main/apps/web/src/routes/routes.tsx): `apps/web/src/routes/routes.tsx`
- [Market overview](https://github.com/tuhama/stromblick/blob/main/apps/web/src/features/overview/OverviewPage.tsx): `apps/web/src/features/overview/OverviewPage.tsx`
- [Generation analysis](https://github.com/tuhama/stromblick/blob/main/apps/web/src/features/overview/generation.ts): `apps/web/src/features/overview/generation.ts`
- [Chart rendering](https://github.com/tuhama/stromblick/blob/main/apps/web/src/charts/DataTable.tsx): `apps/web/src/charts/DataTable.tsx`
- [Tomorrow prices](https://github.com/tuhama/stromblick/blob/main/apps/web/src/features/tomorrow/TomorrowPage.tsx): `apps/web/src/features/tomorrow/TomorrowPage.tsx`
- [Series explorer](https://github.com/tuhama/stromblick/blob/main/apps/web/src/features/explorer/ExplorerPage.tsx): `apps/web/src/features/explorer/ExplorerPage.tsx`
- [Data explanations](https://github.com/tuhama/stromblick/blob/main/apps/web/src/features/explain/ExplainPage.tsx): `apps/web/src/features/explain/ExplainPage.tsx`
- [Query management](https://github.com/tuhama/stromblick/blob/main/apps/web/src/api/query-client.ts): `apps/web/src/api/query-client.ts`
- [API client](https://github.com/tuhama/stromblick/blob/main/apps/web/src/api/client.ts): `apps/web/src/api/client.ts`

### Shared contracts

- [Data contracts](https://github.com/tuhama/stromblick/blob/main/packages/shared/src/readings.ts): `packages/shared/src/readings.ts`

### Other components

- **SMARD data**
- **Dashboard user**

## Connections

- SMARD data → SMARD client: serves data (evidence: `README.md`)
- Ingest endpoint → Ingest runner: starts job (evidence: `apps/api/src/routes/ingest.ts`)
- Ingest runner → SMARD client: fetches weeks (evidence: `apps/api/src/ingest/run.ts`)
- Ingest runner → Series catalog: ingests series (evidence: `apps/api/src/ingest/run.ts`)
- Ingest runner → Postgres: upserts readings (evidence: `apps/api/src/ingest/run.ts`)
- API service → Ingest endpoint: mounts route (evidence: `apps/api/src/app.ts`)
- API service → Series routes: mounts route (evidence: `apps/api/src/app.ts`)
- API service → Status route: mounts route (evidence: `apps/api/src/app.ts`)
- API service → Health route: mounts route (evidence: `apps/api/src/app.ts`)
- Series routes → Readings loader: loads series (evidence: `apps/api/src/routes/series.ts`)
- Readings loader → Postgres: queries readings (evidence: `apps/api/src/series/load-readings.ts`)
- Series routes → Series catalog: uses catalog (evidence: `apps/api/src/routes/series.ts`)
- Status route → Ingest status: loads status (evidence: `apps/api/src/routes/status.ts`)
- Ingest status → Postgres: reads runs (evidence: `apps/api/src/status/load-status.ts`)
- Dashboard user → Browser app: opens dashboard (evidence: `README.md`)
- Browser app → Page routing: starts router (evidence: `apps/web/src/main.tsx`)
- Page routing → Market overview: routes to page (evidence: `apps/web/src/routes/routes.tsx`)
- Page routing → Tomorrow prices: routes to page (evidence: `apps/web/src/routes/routes.tsx`)
- Page routing → Series explorer: routes to page (evidence: `apps/web/src/routes/routes.tsx`)
- Page routing → Data explanations: routes to page (evidence: `apps/web/src/routes/routes.tsx`)
- Browser app → Query management: provides queries (evidence: `apps/web/src/main.tsx`)
- Market overview → Generation analysis: uses analysis (evidence: `apps/web/src/features/overview/generation.ts`)
- Generation analysis → Chart rendering: builds table data (evidence: `apps/web/src/features/overview/generation.ts`)
- Query management → API client: uses requests (evidence: `apps/web/src/api/query-client.ts`)
- API service → Data contracts: shares schemas (evidence: `README.md`)
- API client → Data contracts: validates responses (evidence: `apps/web/src/api/client.ts`)
