# peterklingelhofer/carbon-lens architecture

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

- Interactive diagram: https://gitdiagram.com/peterklingelhofer/carbon-lens
- Repository: https://github.com/peterklingelhofer/carbon-lens

## Overview

CarbonLens is a cloud-compute carbon measurement and decision product. Users inspect live grid intensity and provenance, then compare regions, route workloads, or schedule them for cleaner hours; organizations can ingest usage for emissions reports and define Green SLAs. The backend combines grid-source integrations and region mapping with routing, scheduling, and reporting services, exposed through an API to a web dashboard and CLI. Several domain branches are documented in the README but their implementation was not sampled; their links are shown only where documented or evidenced by the source index.

Main entry points: [`src/carbonlens/api/routes.py`](https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/api/routes.py) (HTTP API), [`src/carbonlens/api/deps.py`](https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/api/deps.py) (Source selection and cache), [`src/carbonlens/grid/mapper.py`](https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/grid/mapper.py) (Region and zone map), [`src/carbonlens/engine/router.py`](https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/engine/router.py) (Region routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_dashboard["Region dashboard<br/>[Dashboard.tsx]"]
  node_globe["Carbon globe<br/>[CarbonGlobe.tsx]"]
  node_webclient["API client<br/>[client.ts]"]
end

subgraph group_api["API and access"]
  node_api["HTTP API<br/>[routes.py]"]
  node_auth["API key access<br/>[dependencies.py]"]
  node_db[("Application database<br/>[models.py]")]
  node_cli["Command-line client<br/>[main.py]"]
end

subgraph group_carbon["Grid data"]
  node_regions["Region and zone map<br/>[mapper.py]"]
  node_source_setup["Source selection and cache<br/>[deps.py]"]
  node_grid_sources["Grid data integrations"]
  node_marginal["Marginal intensity<br/>[marginal.py]"]
  node_history[("History archive<br/>[history_store.py]")]
  node_citations["Citation corpus"]
end

subgraph group_decisions["Carbon decisions"]
  node_routing["Region routing<br/>[router.py]"]
  node_scheduling["Clean-time scheduling<br/>[engine.py]"]
end

subgraph group_assurance["Reporting and targets"]
  node_compliance_ingest["Usage ingestion<br/>[usage_ingestion.py]"]
  node_compliance_calc["Emissions calculation<br/>[calculator.py]"]
  node_compliance_report["Compliance reports<br/>[reporting.py]"]
  node_sla_routes["SLA management API<br/>[routes.py]"]
  node_sla_engine["SLA checks and reports<br/>[engine.py]"]
  node_sla_store[("SLA persistence<br/>[repository.py]")]
end

node_person(("Engineer or analyst"))

node_person -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_dashboard
node_webapp -->|"routes to"| node_globe
node_dashboard -->|"requests data"| node_webclient
node_globe -->|"requests data"| node_webclient
node_webclient -->|"calls HTTP"| node_api
node_person -.->|"runs commands"| node_cli
node_api -->|"resolves dependencies"| node_source_setup
node_source_setup -->|"selects and wraps"| node_grid_sources
node_source_setup -.->|"provides mapper"| node_regions
node_api -->|"lists regions"| node_regions
node_api -->|"reads history"| node_history
node_api -->|"checks credentials"| node_auth
node_api -->|"routes workloads"| node_routing
node_routing -->|"filters candidates"| node_regions
node_routing -.->|"fetches intensity"| node_source_setup
node_routing -.->|"scores grid readings"| node_grid_sources
node_api -->|"requests best time"| node_scheduling
node_scheduling -->|"maps regions"| node_regions
node_scheduling -->|"fetches forecasts"| node_grid_sources
node_scheduling -.->|"optionally uses"| node_marginal
node_person -->|"queries carbon"| node_api
node_person -->|"provides usage"| node_compliance_ingest
node_api -->|"ingests usage"| node_compliance_ingest
node_api -->|"calculates emissions"| node_compliance_calc
node_compliance_calc -.->|"uses carbon source"| node_source_setup
node_api -->|"generates reports"| node_compliance_report
node_person -->|"defines targets"| node_sla_routes
node_api -->|"serves SLA requests"| node_sla_routes
node_sla_routes -->|"runs checks"| node_sla_engine
node_sla_engine -->|"maps monitored zones"| node_regions
node_sla_engine -.->|"checks live readings"| node_grid_sources
node_sla_routes -->|"reads and writes"| node_sla_store
node_sla_store -.->|"persists records"| node_db
node_person -->|"resolves citations"| node_citations

click node_webapp "https://github.com/peterklingelhofer/carbon-lens/blob/main/web/src/App.tsx"
click node_dashboard "https://github.com/peterklingelhofer/carbon-lens/blob/main/web/src/pages/Dashboard.tsx"
click node_globe "https://github.com/peterklingelhofer/carbon-lens/blob/main/web/src/pages/CarbonGlobe.tsx"
click node_webclient "https://github.com/peterklingelhofer/carbon-lens/blob/main/web/src/api/client.ts"
click node_api "https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/api/routes.py"
click node_auth "https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/auth/dependencies.py"
click node_regions "https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/grid/mapper.py"
click node_source_setup "https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/api/deps.py"
click node_grid_sources "https://github.com/peterklingelhofer/carbon-lens/tree/main/src/carbonlens/carbon_sources"
click node_marginal "https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/carbon_sources/marginal.py"
click node_history "https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/carbon_sources/history_store.py"
click node_routing "https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/engine/router.py"
click node_scheduling "https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/scheduler/engine.py"
click node_compliance_ingest "https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/compliance/usage_ingestion.py"
click node_compliance_calc "https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/compliance/calculator.py"
click node_compliance_report "https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/compliance/reporting.py"
click node_sla_routes "https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/sla/routes.py"
click node_sla_engine "https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/sla/engine.py"
click node_sla_store "https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/sla/repository.py"
click node_db "https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/db/models.py"
click node_citations "https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/citations_generated.py"
click node_cli "https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/cli/main.py"

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_webapp,node_dashboard,node_globe,node_webclient toneBlue
class node_api,node_auth,node_db,node_cli toneAmber
class node_regions,node_source_setup,node_grid_sources,node_marginal,node_history,node_citations toneMint
class node_routing,node_scheduling toneRose
class node_compliance_ingest,node_compliance_calc,node_compliance_report,node_sla_routes,node_sla_engine,node_sla_store,node_person toneIndigo
```

## Components

### Web experience

- [Web application](https://github.com/peterklingelhofer/carbon-lens/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Region dashboard](https://github.com/peterklingelhofer/carbon-lens/blob/main/web/src/pages/Dashboard.tsx): `web/src/pages/Dashboard.tsx`
- [Carbon globe](https://github.com/peterklingelhofer/carbon-lens/blob/main/web/src/pages/CarbonGlobe.tsx): `web/src/pages/CarbonGlobe.tsx`
- [API client](https://github.com/peterklingelhofer/carbon-lens/blob/main/web/src/api/client.ts): `web/src/api/client.ts`

### API and access

- [HTTP API](https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/api/routes.py): `src/carbonlens/api/routes.py`
- [API key access](https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/auth/dependencies.py): `src/carbonlens/auth/dependencies.py`
- [Application database](https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/db/models.py): `src/carbonlens/db/models.py`
- [Command-line client](https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/cli/main.py): `src/carbonlens/cli/main.py`

### Grid data

- [Region and zone map](https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/grid/mapper.py): `src/carbonlens/grid/mapper.py`
- [Source selection and cache](https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/api/deps.py): `src/carbonlens/api/deps.py`
- [Grid data integrations](https://github.com/peterklingelhofer/carbon-lens/tree/main/src/carbonlens/carbon_sources): `src/carbonlens/carbon_sources`
- [Marginal intensity](https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/carbon_sources/marginal.py): `src/carbonlens/carbon_sources/marginal.py`
- [History archive](https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/carbon_sources/history_store.py): `src/carbonlens/carbon_sources/history_store.py`
- [Citation corpus](https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/citations_generated.py): `src/carbonlens/citations_generated.py`

### Carbon decisions

- [Region routing](https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/engine/router.py): `src/carbonlens/engine/router.py`
- [Clean-time scheduling](https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/scheduler/engine.py): `src/carbonlens/scheduler/engine.py`

### Reporting and targets

- [Usage ingestion](https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/compliance/usage_ingestion.py): `src/carbonlens/compliance/usage_ingestion.py`
- [Emissions calculation](https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/compliance/calculator.py): `src/carbonlens/compliance/calculator.py`
- [Compliance reports](https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/compliance/reporting.py): `src/carbonlens/compliance/reporting.py`
- [SLA management API](https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/sla/routes.py): `src/carbonlens/sla/routes.py`
- [SLA checks and reports](https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/sla/engine.py): `src/carbonlens/sla/engine.py`
- [SLA persistence](https://github.com/peterklingelhofer/carbon-lens/blob/main/src/carbonlens/sla/repository.py): `src/carbonlens/sla/repository.py`

### Other components

- **Engineer or analyst**

## Connections

- Engineer or analyst → Web application: uses (evidence: `web/src/App.tsx`)
- Web application → Region dashboard: routes to
- Web application → Carbon globe: routes to
- Region dashboard → API client: requests data (evidence: `web/src/pages/Dashboard.tsx`)
- Carbon globe → API client: requests data (evidence: `web/src/pages/CarbonGlobe.tsx`)
- API client → HTTP API: calls HTTP (evidence: `README.md`)
- Engineer or analyst → Command-line client: runs commands
- HTTP API → Source selection and cache: resolves dependencies (evidence: `src/carbonlens/api/deps.py`)
- Source selection and cache → Grid data integrations: selects and wraps (evidence: `src/carbonlens/api/deps.py`)
- Source selection and cache → Region and zone map: provides mapper (evidence: `src/carbonlens/api/deps.py`)
- HTTP API → Region and zone map: lists regions (evidence: `src/carbonlens/api/routes.py`)
- HTTP API → History archive: reads history (evidence: `src/carbonlens/api/routes.py`)
- HTTP API → API key access: checks credentials (evidence: `src/carbonlens/api/routes.py`)
- HTTP API → Region routing: routes workloads (evidence: `src/carbonlens/api/routes.py`)
- Region routing → Region and zone map: filters candidates (evidence: `src/carbonlens/engine/router.py`)
- Region routing → Source selection and cache: fetches intensity (evidence: `src/carbonlens/api/deps.py`)
- Region routing → Grid data integrations: scores grid readings (evidence: `src/carbonlens/engine/router.py`)
- HTTP API → Clean-time scheduling: requests best time (evidence: `src/carbonlens/api/routes.py`)
- Clean-time scheduling → Region and zone map: maps regions (evidence: `src/carbonlens/scheduler/engine.py`)
- Clean-time scheduling → Grid data integrations: fetches forecasts (evidence: `src/carbonlens/scheduler/engine.py`)
- Clean-time scheduling → Marginal intensity: optionally uses (evidence: `src/carbonlens/scheduler/engine.py`)
- Engineer or analyst → HTTP API: queries carbon (evidence: `README.md`)
- Engineer or analyst → Usage ingestion: provides usage (evidence: `README.md`)
- HTTP API → Usage ingestion: ingests usage
- HTTP API → Emissions calculation: calculates emissions
- Emissions calculation → Source selection and cache: uses carbon source
- HTTP API → Compliance reports: generates reports
- Engineer or analyst → SLA management API: defines targets (evidence: `README.md`)
- HTTP API → SLA management API: serves SLA requests (evidence: `src/carbonlens/main.py`)
- SLA management API → SLA checks and reports: runs checks (evidence: `src/carbonlens/sla/routes.py`)
- SLA checks and reports → Region and zone map: maps monitored zones (evidence: `src/carbonlens/sla/engine.py`)
- SLA checks and reports → Grid data integrations: checks live readings (evidence: `src/carbonlens/sla/engine.py`)
- SLA management API → SLA persistence: reads and writes (evidence: `src/carbonlens/sla/routes.py`)
- SLA persistence → Application database: persists records
- Engineer or analyst → Citation corpus: resolves citations (evidence: `README.md`)
