# roel-karstens/gridlens architecture

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

- Interactive diagram: https://gitdiagram.com/roel-karstens/gridlens
- Repository: https://github.com/roel-karstens/gridlens

## Overview

GridLens lets authenticated users explore current and historical electricity demand and generation, and compare supported European countries. Its data path runs from ENTSO-E through fetching, parsing, normalization, ingestion and database storage; authenticated API routes query that data for the React interface. The README also documents project management. Frontend API-client and Supabase implementation files are absent from the supplied tree, so those connections are shown only where the excerpts or README support them; unsampled page internals are not inferred.

Main entry points: [`backend/app/api/electricity.py`](https://github.com/roel-karstens/gridlens/blob/main/backend/app/api/electricity.py) (Electricity endpoints), [`frontend/src/App.tsx`](https://github.com/roel-karstens/gridlens/blob/main/frontend/src/App.tsx) (Application shell), [`frontend/src/pages/DashboardPage.tsx`](https://github.com/roel-karstens/gridlens/blob/main/frontend/src/pages/DashboardPage.tsx) (Dashboard), [`backend/app/services/ingestion.py`](https://github.com/roel-karstens/gridlens/blob/main/backend/app/services/ingestion.py) (Ingestion service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web experience"]
  node_app["Application shell<br/>[App.tsx]"]
  node_authpage["Sign-in<br/>[AuthPage.tsx]"]
  node_dashboard["Dashboard<br/>[DashboardPage.tsx]"]
  node_history["History view<br/>[HistoryPage.tsx]"]
  node_comparison["Country comparison<br/>[ComparisonPage.tsx]"]
  node_electricity_widgets["Metric widgets"]
  node_generation_chart["Generation chart"]
  node_country_selector["Country selector"]
  node_electricity_hook["Electricity data hook<br/>[useElectricity.ts]"]
end

subgraph group_api["API and access"]
  node_fastapi["FastAPI application<br/>[main.py]"]
  node_electricity_api["Electricity endpoints<br/>[electricity.py]"]
  node_auth["JWT authentication<br/>[auth.py]"]
  node_database_session["Database sessions<br/>[dependencies.py]"]
end

subgraph group_data["Electricity data"]
  node_electricity_service["Electricity queries<br/>[electricity.py]"]
  node_observations[("Observation records<br/>[electricity.py]")]
  node_ingestion["Ingestion service<br/>[ingestion.py]"]
  node_entsoe_client["ENTSO-E client<br/>[client.py]"]
  node_entsoe_parser["XML parser<br/>[parser.py]"]
  node_entsoe_types["Response models<br/>[models.py]"]
  node_entsoe_config["Country and technology mappings<br/>[constants.py]"]
end

subgraph group_projects["Projects"]
  node_projects_api["Project endpoints<br/>[projects.py]"]
  node_project_service["Project operations<br/>[project.py]"]
  node_project_model[("Project records<br/>[project.py]")]
  node_project_pages["Project interface<br/>[ProjectsPage.tsx]"]
  node_project_form["Project form<br/>[ProjectForm.tsx]"]
  node_project_list["Project list<br/>[ProjectList.tsx]"]
end

node_user(("User"))
node_entsoe["ENTSO-E platform"]

node_user -.->|"uses"| node_app
node_app -->|"shows signed out"| node_authpage
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_history
node_app -->|"routes to"| node_comparison
node_dashboard -->|"renders"| node_electricity_widgets
node_dashboard -->|"renders"| node_generation_chart
node_dashboard -->|"renders"| node_country_selector
node_dashboard -->|"fetches via"| node_electricity_hook
node_electricity_hook -.->|"requests data"| node_electricity_api
node_fastapi -->|"registers"| node_electricity_api
node_fastapi -->|"registers"| node_projects_api
node_electricity_api -->|"authenticates with"| node_auth
node_electricity_api -->|"gets session"| node_database_session
node_electricity_api -->|"queries"| node_electricity_service
node_electricity_api -->|"lists supported countries"| node_entsoe_config
node_electricity_service -->|"queries"| node_observations
node_ingestion -->|"fetches through"| node_entsoe_client
node_ingestion -->|"parses with"| node_entsoe_parser
node_ingestion -->|"writes"| node_observations
node_ingestion -->|"uses mappings"| node_entsoe_config
node_entsoe_parser -->|"creates typed data"| node_entsoe_types
node_entsoe_parser -->|"uses mappings"| node_entsoe_config
node_entsoe_client -->|"requests data"| node_entsoe
node_projects_api -->|"authenticates with"| node_auth
node_projects_api -->|"gets session"| node_database_session
node_projects_api -->|"delegates to"| node_project_service
node_project_service -->|"queries"| node_project_model
node_project_pages -->|"renders"| node_project_form
node_project_pages -->|"renders"| node_project_list

click node_app "https://github.com/roel-karstens/gridlens/blob/main/frontend/src/App.tsx"
click node_authpage "https://github.com/roel-karstens/gridlens/blob/main/frontend/src/pages/AuthPage.tsx"
click node_dashboard "https://github.com/roel-karstens/gridlens/blob/main/frontend/src/pages/DashboardPage.tsx"
click node_history "https://github.com/roel-karstens/gridlens/blob/main/frontend/src/pages/HistoryPage.tsx"
click node_comparison "https://github.com/roel-karstens/gridlens/blob/main/frontend/src/pages/ComparisonPage.tsx"
click node_electricity_widgets "https://github.com/roel-karstens/gridlens/blob/main/frontend/src/components/ElectricityCard.tsx"
click node_generation_chart "https://github.com/roel-karstens/gridlens/blob/main/frontend/src/components/GenerationChart.tsx"
click node_country_selector "https://github.com/roel-karstens/gridlens/blob/main/frontend/src/components/CountrySelector.tsx"
click node_electricity_hook "https://github.com/roel-karstens/gridlens/blob/main/frontend/src/hooks/useElectricity.ts"
click node_fastapi "https://github.com/roel-karstens/gridlens/blob/main/backend/app/main.py"
click node_electricity_api "https://github.com/roel-karstens/gridlens/blob/main/backend/app/api/electricity.py"
click node_auth "https://github.com/roel-karstens/gridlens/blob/main/backend/app/core/auth.py"
click node_database_session "https://github.com/roel-karstens/gridlens/blob/main/backend/app/dependencies.py"
click node_electricity_service "https://github.com/roel-karstens/gridlens/blob/main/backend/app/services/electricity.py"
click node_observations "https://github.com/roel-karstens/gridlens/blob/main/backend/app/models/electricity.py"
click node_ingestion "https://github.com/roel-karstens/gridlens/blob/main/backend/app/services/ingestion.py"
click node_entsoe_client "https://github.com/roel-karstens/gridlens/blob/main/backend/app/integrations/entsoe/client.py"
click node_entsoe_parser "https://github.com/roel-karstens/gridlens/blob/main/backend/app/integrations/entsoe/parser.py"
click node_entsoe_types "https://github.com/roel-karstens/gridlens/blob/main/backend/app/integrations/entsoe/models.py"
click node_entsoe_config "https://github.com/roel-karstens/gridlens/blob/main/backend/app/integrations/entsoe/constants.py"
click node_projects_api "https://github.com/roel-karstens/gridlens/blob/main/backend/app/api/projects.py"
click node_project_service "https://github.com/roel-karstens/gridlens/blob/main/backend/app/services/project.py"
click node_project_model "https://github.com/roel-karstens/gridlens/blob/main/backend/app/models/project.py"
click node_project_pages "https://github.com/roel-karstens/gridlens/blob/main/frontend/src/pages/ProjectsPage.tsx"
click node_project_form "https://github.com/roel-karstens/gridlens/blob/main/frontend/src/components/ProjectForm.tsx"
click node_project_list "https://github.com/roel-karstens/gridlens/blob/main/frontend/src/components/ProjectList.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_app,node_authpage,node_dashboard,node_history,node_comparison,node_electricity_widgets,node_generation_chart,node_country_selector,node_electricity_hook,node_user toneBlue
class node_fastapi,node_electricity_api,node_auth,node_database_session toneAmber
class node_electricity_service,node_observations,node_ingestion,node_entsoe_client,node_entsoe_parser,node_entsoe_types,node_entsoe_config toneMint
class node_projects_api,node_project_service,node_project_model,node_project_pages,node_project_form,node_project_list toneRose
class node_entsoe toneIndigo
```

## Components

### Web experience

- [Application shell](https://github.com/roel-karstens/gridlens/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Sign-in](https://github.com/roel-karstens/gridlens/blob/main/frontend/src/pages/AuthPage.tsx): `frontend/src/pages/AuthPage.tsx`
- [Dashboard](https://github.com/roel-karstens/gridlens/blob/main/frontend/src/pages/DashboardPage.tsx): `frontend/src/pages/DashboardPage.tsx`
- [History view](https://github.com/roel-karstens/gridlens/blob/main/frontend/src/pages/HistoryPage.tsx): `frontend/src/pages/HistoryPage.tsx`
- [Country comparison](https://github.com/roel-karstens/gridlens/blob/main/frontend/src/pages/ComparisonPage.tsx): `frontend/src/pages/ComparisonPage.tsx`
- [Metric widgets](https://github.com/roel-karstens/gridlens/blob/main/frontend/src/components/ElectricityCard.tsx): `frontend/src/components/ElectricityCard.tsx`
- [Generation chart](https://github.com/roel-karstens/gridlens/blob/main/frontend/src/components/GenerationChart.tsx): `frontend/src/components/GenerationChart.tsx`
- [Country selector](https://github.com/roel-karstens/gridlens/blob/main/frontend/src/components/CountrySelector.tsx): `frontend/src/components/CountrySelector.tsx`
- [Electricity data hook](https://github.com/roel-karstens/gridlens/blob/main/frontend/src/hooks/useElectricity.ts): `frontend/src/hooks/useElectricity.ts`

### API and access

- [FastAPI application](https://github.com/roel-karstens/gridlens/blob/main/backend/app/main.py): `backend/app/main.py`
- [Electricity endpoints](https://github.com/roel-karstens/gridlens/blob/main/backend/app/api/electricity.py): `backend/app/api/electricity.py`
- [JWT authentication](https://github.com/roel-karstens/gridlens/blob/main/backend/app/core/auth.py): `backend/app/core/auth.py`
- [Database sessions](https://github.com/roel-karstens/gridlens/blob/main/backend/app/dependencies.py): `backend/app/dependencies.py`

### Electricity data

- [Electricity queries](https://github.com/roel-karstens/gridlens/blob/main/backend/app/services/electricity.py): `backend/app/services/electricity.py`
- [Observation records](https://github.com/roel-karstens/gridlens/blob/main/backend/app/models/electricity.py): `backend/app/models/electricity.py`
- [Ingestion service](https://github.com/roel-karstens/gridlens/blob/main/backend/app/services/ingestion.py): `backend/app/services/ingestion.py`
- [ENTSO-E client](https://github.com/roel-karstens/gridlens/blob/main/backend/app/integrations/entsoe/client.py): `backend/app/integrations/entsoe/client.py`
- [XML parser](https://github.com/roel-karstens/gridlens/blob/main/backend/app/integrations/entsoe/parser.py): `backend/app/integrations/entsoe/parser.py`
- [Response models](https://github.com/roel-karstens/gridlens/blob/main/backend/app/integrations/entsoe/models.py): `backend/app/integrations/entsoe/models.py`
- [Country and technology mappings](https://github.com/roel-karstens/gridlens/blob/main/backend/app/integrations/entsoe/constants.py): `backend/app/integrations/entsoe/constants.py`

### Projects

- [Project endpoints](https://github.com/roel-karstens/gridlens/blob/main/backend/app/api/projects.py): `backend/app/api/projects.py`
- [Project operations](https://github.com/roel-karstens/gridlens/blob/main/backend/app/services/project.py): `backend/app/services/project.py`
- [Project records](https://github.com/roel-karstens/gridlens/blob/main/backend/app/models/project.py): `backend/app/models/project.py`
- [Project interface](https://github.com/roel-karstens/gridlens/blob/main/frontend/src/pages/ProjectsPage.tsx): `frontend/src/pages/ProjectsPage.tsx`
- [Project form](https://github.com/roel-karstens/gridlens/blob/main/frontend/src/components/ProjectForm.tsx): `frontend/src/components/ProjectForm.tsx`
- [Project list](https://github.com/roel-karstens/gridlens/blob/main/frontend/src/components/ProjectList.tsx): `frontend/src/components/ProjectList.tsx`

### Other components

- **User**
- **ENTSO-E platform**

## Connections

- User → Application shell: uses
- Application shell → Sign-in: shows signed out (evidence: `frontend/src/App.tsx`)
- Application shell → Dashboard: routes to (evidence: `frontend/src/App.tsx`)
- Application shell → History view: routes to (evidence: `frontend/src/App.tsx`)
- Application shell → Country comparison: routes to (evidence: `frontend/src/App.tsx`)
- Dashboard → Metric widgets: renders (evidence: `frontend/src/pages/DashboardPage.tsx`)
- Dashboard → Generation chart: renders (evidence: `frontend/src/pages/DashboardPage.tsx`)
- Dashboard → Country selector: renders (evidence: `frontend/src/pages/DashboardPage.tsx`)
- Dashboard → Electricity data hook: fetches via (evidence: `frontend/src/pages/DashboardPage.tsx`)
- Electricity data hook → Electricity endpoints: requests data
- FastAPI application → Electricity endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI application → Project endpoints: registers (evidence: `backend/app/main.py`)
- Electricity endpoints → JWT authentication: authenticates with (evidence: `backend/app/api/electricity.py`)
- Electricity endpoints → Database sessions: gets session (evidence: `backend/app/api/electricity.py`)
- Electricity endpoints → Electricity queries: queries (evidence: `backend/app/api/electricity.py`)
- Electricity endpoints → Country and technology mappings: lists supported countries (evidence: `backend/app/api/electricity.py`)
- Electricity queries → Observation records: queries (evidence: `backend/app/services/electricity.py`)
- Ingestion service → ENTSO-E client: fetches through (evidence: `backend/app/services/ingestion.py`)
- Ingestion service → XML parser: parses with (evidence: `backend/app/services/ingestion.py`)
- Ingestion service → Observation records: writes (evidence: `backend/app/services/ingestion.py`)
- Ingestion service → Country and technology mappings: uses mappings (evidence: `backend/app/services/ingestion.py`)
- XML parser → Response models: creates typed data (evidence: `backend/app/integrations/entsoe/parser.py`)
- XML parser → Country and technology mappings: uses mappings (evidence: `backend/app/integrations/entsoe/parser.py`)
- ENTSO-E client → ENTSO-E platform: requests data (evidence: `README.md`)
- Project endpoints → JWT authentication: authenticates with (evidence: `backend/app/api/projects.py`)
- Project endpoints → Database sessions: gets session (evidence: `backend/app/api/projects.py`)
- Project endpoints → Project operations: delegates to (evidence: `backend/app/api/projects.py`)
- Project operations → Project records: queries (evidence: `backend/app/services/project.py`)
- Project interface → Project form: renders (evidence: `frontend/src/pages/ProjectsPage.tsx`)
- Project interface → Project list: renders (evidence: `frontend/src/pages/ProjectsPage.tsx`)
