How peterklingelhofer/carbon-lens works
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: routes.py HTTP API · deps.py Source selection and cache · mapper.py Region and zone map · router.py Region routing
Components 23
Web experience
- Web application
web/src/App.tsx - Region dashboard
web/src/pages/Dashboard.tsx - Carbon globe
web/src/pages/CarbonGlobe.tsx - API client
web/src/api/client.ts
API and access
- HTTP API
src/carbonlens/api/routes.py - API key access
src/carbonlens/auth/dependencies.py - Application database
src/carbonlens/db/models.py - Command-line client
src/carbonlens/cli/main.py
Grid data
- Region and zone map
src/carbonlens/grid/mapper.py - Source selection and cache
src/carbonlens/api/deps.py - Grid data integrations
src/carbonlens/carbon_sources - Marginal intensity
src/carbonlens/carbon_sources/marginal.py - History archive
src/carbonlens/carbon_sources/history_store.py - Citation corpus
src/carbonlens/citations_generated.py
Carbon decisions
- Region routing
src/carbonlens/engine/router.py - Clean-time scheduling
src/carbonlens/scheduler/engine.py
Reporting and targets
- Usage ingestion
src/carbonlens/compliance/usage_ingestion.py - Emissions calculation
src/carbonlens/compliance/calculator.py - Compliance reports
src/carbonlens/compliance/reporting.py - SLA management API
src/carbonlens/sla/routes.py - SLA checks and reports
src/carbonlens/sla/engine.py - SLA persistence
src/carbonlens/sla/repository.py
Other components
- Engineer or analyst
Connections 35
- Engineer or analyst → Web application: uses
web/src/App.tsx - Web application → Region dashboard: routes to
- Web application → Carbon globe: routes to
- Region dashboard → API client: requests data
web/src/pages/Dashboard.tsx - Carbon globe → API client: requests data
web/src/pages/CarbonGlobe.tsx - API client → HTTP API: calls HTTP
README.md - Engineer or analyst → Command-line client: runs commands
- HTTP API → Source selection and cache: resolves dependencies
src/carbonlens/api/deps.py - Source selection and cache → Grid data integrations: selects and wraps
src/carbonlens/api/deps.py - Source selection and cache → Region and zone map: provides mapper
src/carbonlens/api/deps.py - HTTP API → Region and zone map: lists regions
src/carbonlens/api/routes.py - HTTP API → History archive: reads history
src/carbonlens/api/routes.py - HTTP API → API key access: checks credentials
src/carbonlens/api/routes.py - HTTP API → Region routing: routes workloads
src/carbonlens/api/routes.py - Region routing → Region and zone map: filters candidates
src/carbonlens/engine/router.py - Region routing → Source selection and cache: fetches intensity
src/carbonlens/api/deps.py - Region routing → Grid data integrations: scores grid readings
src/carbonlens/engine/router.py - HTTP API → Clean-time scheduling: requests best time
src/carbonlens/api/routes.py - Clean-time scheduling → Region and zone map: maps regions
src/carbonlens/scheduler/engine.py - Clean-time scheduling → Grid data integrations: fetches forecasts
src/carbonlens/scheduler/engine.py - Clean-time scheduling → Marginal intensity: optionally uses
src/carbonlens/scheduler/engine.py - Engineer or analyst → HTTP API: queries carbon
README.md - Engineer or analyst → Usage ingestion: provides usage
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
README.md - HTTP API → SLA management API: serves SLA requests
src/carbonlens/main.py - SLA management API → SLA checks and reports: runs checks
src/carbonlens/sla/routes.py - SLA checks and reports → Region and zone map: maps monitored zones
src/carbonlens/sla/engine.py - SLA checks and reports → Grid data integrations: checks live readings
src/carbonlens/sla/engine.py - SLA management API → SLA persistence: reads and writes
src/carbonlens/sla/routes.py - SLA persistence → Application database: persists records
- Engineer or analyst → Citation corpus: resolves citations
README.md