How mlco2/codecarbon works
Project type and purpose
• CodeCarbon is primarily an open-source Python library to estimate and track carbon emissions (“SDK”).
• It ships with a companion backend service (“carbonserver”) exposing a REST API for storing and visualizing emissions experiments.
• A Next.js-based frontend web application (“webapp”) provides the user dashboard.
• There is also a lightweight Dash-style “dashboard” directory for embedding visualizations, CLI tools, and Ansible/docker deploy workflows.
• Overall it’s a full-stack SaaS/API offering plus SDK.
High-level components
A. CodeCarbon Python SDK (“Library”)
• Emission measurement core (cpu, gpu, ram modules, resource tracker).
• CO₂ intensity providers (co2_signal, cloud, private_infra data).
• Output channels (console, file, HTTP, Prometheus, etc.).
• CLI entry points (codecarbon init, codecarbon monitor).
B. carbonserver (FastAPI-based backend)
• Routers (authenticate, users, organizations, projects, runs, emissions…)
• Services / business logic (auth_service, run_service, emission_service…)
• Use cases (hexagonal “usecases” folder for domain-specific aggregation).
• Repositories (SQLAlchemy models + repository classes).
• Database (PostgreSQL + Alembic migrations).
• API key management & Fief auth integration.
C. Frontend Webapp (Next.js)
• Public and private routes, SSR + client components.
• API client layer (helpers/api-client.ts).
• Authentication middleware (Fief).
• UI components, charts, modals (Radix UI + custom charts).
D. Dash-style “dashboard” (Plotly Dash / Flask)
• Data loader + layout + callbacks for standalone visualization.
E. Deployment & infra
• Docker Compose + Traefik, Ansible roles for “CLI as a service”
• GitHub Actions CI/CD pipelines (build, test, release).
• Environment configurations (.env.*).
F. Documentation & examples
• Sphinx-generated static docs
• An examples folder demonstrating SDK usage.
Relationships & data flows
• The SDK can run standalone: it computes emissions and writes to local file or console.
• If save_to_api = True, SDK POSTs emission records to carbonserver API (HTTP).
• Webapp front end calls the same carbonserver REST endpoints to fetch experiments, runs, emissions aggregates.
• carbonserver persists to PostgreSQL, runs Alembic migrations at startup.
• carbonserver may call out to external intensity APIs (e.g., CO₂ Signal) when the SDK asks it for current intensity.
• Dashboard is an independent component that also queries the API or loads local CSVs.
• Deploy layer packages SDK as CLI-as-a-service, spins up carbonserver + webapp via Docker/Traefik.
• CI/CD workflows lint, test, build Docker images, deploy to staging/production.
Architectural patterns & design principles
• Hexagonal / Clean Architecture in carbonserver: separation of routers (controllers), services (use cases), repositories (data access), domain models.
• Layered architecture in the SDK: measurement → intensity calculation → output.
• Micro-frontend style in webapp: clear split between public pages and authenticated dashboard pages.
• Infrastructure as code: Docker + Ansible + CI workflows.
• Modular monorepo: well-scoped subdirectories for each concern.