# mlco2/codecarbon architecture

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

- Interactive diagram: https://gitdiagram.com/mlco2/codecarbon
- Repository: https://github.com/mlco2/codecarbon

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% SDK Layer
    subgraph "SDK (Python Module)" 
        direction TB
        Tracker["Emission Measurement Core"]:::sdk
        Providers["CO₂ Intensity Providers"]:::sdk
        Outputs["Output Channels"]:::sdk
        CLI["CLI Entry Points"]:::sdk
    end

    %% Backend API
    subgraph "Carbonserver API (FastAPI)" 
        direction TB
        Controllers["Routers (authenticate, users, projects…)"]:::backend
        Services["Services / Business Logic"]:::backend
        Usecases["Use Cases (hexagonal)"]:::backend
        Repos["Repositories & Models"]:::backend
        Entry["Main & Container Setup"]:::backend
        Migrations["Alembic Migrations"]:::backend
    end

    %% Database
    PostgreSQL[(PostgreSQL)]:::db

    %% Frontend Webapp
    subgraph "Webapp (Next.js)" 
        direction TB
        Routes["Public & Private Routes"]:::frontend
        APIClient["API Client Layer"]:::frontend
        AuthMW["Authentication Middleware (Fief)"]:::frontend
        UI["UI Components & Charts"]:::frontend
    end

    %% Dashboard
    subgraph "Dashboard (Plotly Dash / Flask)" 
        direction TB
        DL["Data Loader"]:::external
        Layout["Layout"]:::external
        Callbacks["Callbacks"]:::external
        Funcs["Functions"]:::external
    end

    %% Deployment & Infra
    subgraph "Deployment & Infrastructure" 
        direction TB
        DockerCompose["Docker Compose & Traefik Configs"]:::infra
        Ansible["Ansible Roles (CLI as a Service)"]:::infra
        EnvConfigs["Environment Configurations"]:::infra
    end

    %% CI/CD
    subgraph "CI/CD (GitHub Actions)" 
        Workflows["Workflows"]:::cicd
    end

    %% External Services
    subgraph "External Services" 
        direction TB
        CO2API["CO₂ Signal & Cloud APIs"]:::external
        FiefService["Fief Identity Service"]:::external
    end

    %% Relationships
    Tracker -->|"POST /runs"| Controllers
    Providers --> Controllers
    Controllers --> Services
    Services --> Usecases
    Usecases --> Repos
    Repos --> PostgreSQL
    Migrations --> PostgreSQL
    Controllers -->|"calls"| CO2API
    CLI --> Tracker
    CLI -->|"save_to_api=True"| Controllers

    Routes -->|"GET/POST"| Controllers
    APIClient --> Controllers
    AuthMW --> FiefService
    UI --> APIClient

    DL --> Controllers
    DL -->|"or local CSV"| Funcs
    Layout --> DL
    Callbacks --> Layout

    DockerCompose --> Controllers
    DockerCompose --> Routes
    Ansible --> CLI

    Workflows --> DockerCompose
    Workflows --> Ansible

    %% Click Events - SDK
    click Tracker "https://github.com/mlco2/codecarbon/blob/master/codecarbon/core/measure.py"
    click Providers "https://github.com/mlco2/codecarbon/blob/master/codecarbon/core/co2_signal.py"
    click Providers "https://github.com/mlco2/codecarbon/blob/master/codecarbon/core/cloud.py"
    click Providers "https://github.com/mlco2/codecarbon/tree/master/codecarbon/data/private_infra"
    click Outputs "https://github.com/mlco2/codecarbon/blob/master/codecarbon/output_methods/file.py"
    click Outputs "https://github.com/mlco2/codecarbon/blob/master/codecarbon/output_methods/http.py"
    click Outputs "https://github.com/mlco2/codecarbon/blob/master/codecarbon/output_methods/metrics/prometheus.py"
    click Outputs "https://github.com/mlco2/codecarbon/blob/master/codecarbon/output_methods/logger.py"
    click CLI "https://github.com/mlco2/codecarbon/blob/master/codecarbon/cli/main.py"
    click CLI "https://github.com/mlco2/codecarbon/blob/master/codecarbon/cli/cli_utils.py"

    %% Click Events - Backend
    click Controllers "https://github.com/mlco2/codecarbon/tree/master/carbonserver/carbonserver/api/routers"
    click Services "https://github.com/mlco2/codecarbon/tree/master/carbonserver/carbonserver/api/services"
    click Usecases "https://github.com/mlco2/codecarbon/tree/master/carbonserver/carbonserver/api/usecases"
    click Repos "https://github.com/mlco2/codecarbon/tree/master/carbonserver/carbonserver/api/infra/repositories"
    click Repos "https://github.com/mlco2/codecarbon/blob/master/carbonserver/carbonserver/api/infra/database/sql_models.py"
    click Migrations "https://github.com/mlco2/codecarbon/tree/master/carbonserver/carbonserver/database/alembic"
    click Entry "https://github.com/mlco2/codecarbon/blob/master/carbonserver/main.py"
    click Entry "https://github.com/mlco2/codecarbon/blob/master/carbonserver/container.py"

    %% Click Events - Frontend
    click Routes "https://github.com/mlco2/codecarbon/tree/master/webapp/src/app/(dashboard)"
    click Routes "https://github.com/mlco2/codecarbon/tree/master/webapp/src/app/public"
    click APIClient "https://github.com/mlco2/codecarbon/blob/master/webapp/src/helpers/api-client.ts"
    click AuthMW "https://github.com/mlco2/codecarbon/blob/master/webapp/src/helpers/fief.ts"
    click AuthMW "https://github.com/mlco2/codecarbon/blob/master/webapp/src/middleware.ts"
    click UI "https://github.com/mlco2/codecarbon/tree/master/webapp/src/components"

    %% Click Events - Dashboard
    click DL "https://github.com/mlco2/codecarbon/blob/master/dashboard/data/data_loader.py"
    click Layout "https://github.com/mlco2/codecarbon/blob/master/dashboard/layout/app.py"
    click Callbacks "https://github.com/mlco2/codecarbon/blob/master/dashboard/layout/callbacks.py"
    click Funcs "https://github.com/mlco2/codecarbon/tree/master/dashboard/functions"

    %% Click Events - Deployment & Infra
    click DockerCompose "https://github.com/mlco2/codecarbon/blob/master/docker-compose.yml"
    click DockerCompose "https://github.com/mlco2/codecarbon/blob/master/deploy/traefik-compose.yml"
    click DockerCompose "https://github.com/mlco2/codecarbon/blob/master/deploy/fief-compose.yml"
    click Ansible "https://github.com/mlco2/codecarbon/tree/master/deploy/ansible/codecarbon_cli_as_a_service"
    click EnvConfigs "https://github.com/mlco2/codecarbon/blob/master/.env.example"
    click EnvConfigs "https://github.com/mlco2/codecarbon/blob/master/deploy/.env.example"
    click EnvConfigs "https://github.com/mlco2/codecarbon/blob/master/deploy/.env.webapp.example"

    %% Click Events - CI/CD
    click Workflows "https://github.com/mlco2/codecarbon/tree/master/.github/workflows"

    %% Styles
    classDef sdk fill:#E0F7FA,stroke:#006064,color:#004D40
    classDef backend fill:#E8F5E9,stroke:#1B5E20,color:#2E7D32
    classDef db fill:#FFF3E0,stroke:#EF6C00,color:#E65100
    classDef frontend fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C
    classDef infra fill:#ECEFF1,stroke:#37474F,color:#263238
    classDef cicd fill:#FFFDE7,stroke:#F9A825,color:#F57F17
    classDef external fill:#ECEFF1,stroke:#90A4AE,color:#607D8B
```
