# electricitymaps/electricitymaps-contrib architecture

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

- Interactive diagram: https://gitdiagram.com/electricitymaps/electricitymaps-contrib
- Repository: https://github.com/electricitymaps/electricitymaps-contrib

## Overview

##### Project type and purpose
- This is a full-stack, open-source data-pipeline and visualization platform (“Electricity Maps”) that:
- Ingests raw grid data via dozens of Python “parser” modules from official external sources (TSOs, government APIs, etc.).
- Runs processing (flow-tracing, CO₂ intensity calculation) in Python code (in `/electricitymap/contrib` and top-level scripts).
- Publishes a RESTful API (mockserver in Node.js for local dev, real API likely hosted by the Python backend).
- Hosts a React-based web client (`/web`) and an Ionic/Capacitor mobile app (`/mobileapp`) that consume that API.
- Contains utility scripts (`/scripts`) and configuration (`/config`) for zone definitions, emission factors, capacities.

##### High-level architecture components
a. External Data Sources
– Live TSO feeds, CSV/JSON/XML endpoints, public APIs, spreadsheets.
b. Parsers & Ingestion Service (Python)
– Each module in `/parsers` or `/electricitymap/contrib/capacity_parsers` fetches, normalizes, validates.
– Runs on a schedule (cron, Docker, Earthly).
c. Processing & Core Library
– Flow-tracing algorithm, CO₂ intensity parameters in `/electricitymap/contrib/config` and `/scripts`.
– Capacity update logic in `capacity_update.py` and scripts under `/scripts`.
d. Configuration & Data Store
– YAML/JSON zone definitions (`/config/zones`, `/config/exchanges`, `/config/data_centers`).
– Defaults (`defaults.yaml`), retired zones, emission factor sources.
– Final processed time-series stored in an in-memory DB or time-series DB (not shown, but implied).
e. API Layer
– Node.js mockserver (`/mockserver`) serves `/v10/state`, `/v10/details`, `/v10/meta`, `/v10/gfs` endpoints with static JSON for dev.
– Real backend API (Python or Node, not in this repo) serving identical endpoints.
f. Web Front-end (React + Vite)
– Lives in `/web/src`.
– Static assets under `/web/public`.
– Fetches from `/api/getState`, `/api/getZone`, `/api/getMeta`, `/api/getWeatherData`.
– Handles localization, map rendering, charts.
g. Mobile App (Ionic/Capacitor)
– Code in `/mobileapp`.
– Native wrappers (Android in `android/`, iOS in `ios/`), web code in `src`.
– Uses Capacitor to call the same REST API as the web.
h. CI/CD & DevOps
– `.github/workflows` for CI, code scanning, preview deployments.
– Earthfile & Dockerfiles for reproducible builds.
– Devcontainer for local VSCode.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Systems"
        ext["External Data Sources"]:::external
    end

    subgraph "Ingestion Layer"
        parsers["Parsers & Ingestion Service"]:::backend
        capparsers["Capacity Parsers"]:::backend
    end

    subgraph "Processing Layer"
        coreconfig["Processing Config"]:::backend
        corelib["Core Library"]:::backend
        capupdate["Capacity Update Script"]:::backend
        scripts["Processing Scripts"]:::backend
    end

    subgraph "Storage & Config"
        configstore["Configuration Store"]:::external
        datastore["Time-Series DB"]:::external
    end

    subgraph "API Layer"
        mock["Mock API (Node.js)"]:::backend
        realapi["Real API"]:::backend
    end

    subgraph "Clients"
        web["Web Client (React SPA)"]:::frontend
        mobile["Mobile App (Ionic/Capacitor)"]:::frontend
    end

    subgraph "CI/CD & DevOps"
        workflows["CI/CD Workflows"]:::dev
        devcontainer["Devcontainer"]:::dev
        earthly["Earthfile"]:::dev
        dockerignore[".dockerignore"]:::dev
        parserdocker["parsers.dockerfile"]:::dev
    end

    %% Data Flows
    ext -->|HTTP/CSV/XML| parsers
    parsers --> capparsers
    parsers --> corelib
    capparsers --> corelib
    coreconfig --> corelib
    scripts --> corelib
    corelib --> datastore
    configstore --> datastore
    configstore --> corelib
    datastore --> mock
    configstore --> mock
    mock -.->|"dev substitute"| realapi
    datastore --> realapi
    configstore --> realapi
    web -->|HTTP JSON| mock
    mobile -->|HTTP JSON| mock
    web -->|HTTP JSON| realapi
    mobile -->|HTTP JSON| realapi
    workflows --> parsers
    workflows --> mock
    workflows --> web
    workflows --> mobile
    workflows --> realapi
    earthly --> parsers
    earthly --> realapi
    dockerignore --> parsers
    parserdocker --> parsers
    devcontainer --> parsers
    devcontainer --> web

    %% Click Events
    click parsers "https://github.com/electricitymaps/electricitymaps-contrib/tree/master/parsers/"
    click capparsers "https://github.com/electricitymaps/electricitymaps-contrib/tree/master/electricitymap/contrib/capacity_parsers/"
    click coreconfig "https://github.com/electricitymaps/electricitymaps-contrib/tree/master/electricitymap/contrib/config/"
    click corelib "https://github.com/electricitymaps/electricitymaps-contrib/tree/master/electricitymap/contrib/lib/"
    click capupdate "https://github.com/electricitymaps/electricitymaps-contrib/blob/master/capacity_update.py"
    click scripts "https://github.com/electricitymaps/electricitymaps-contrib/tree/master/scripts/"
    click configstore "https://github.com/electricitymaps/electricitymaps-contrib/tree/master/config/"
    click mock "https://github.com/electricitymaps/electricitymaps-contrib/tree/master/mockserver/"
    click web "https://github.com/electricitymaps/electricitymaps-contrib/tree/master/web/"
    click mobile "https://github.com/electricitymaps/electricitymaps-contrib/tree/master/mobileapp/"
    click workflows "https://github.com/electricitymaps/electricitymaps-contrib/tree/master/.github/workflows/"
    click devcontainer "https://github.com/electricitymaps/electricitymaps-contrib/tree/master/.devcontainer/"
    click earthly "https://github.com/electricitymaps/electricitymaps-contrib/tree/master/Earthfile"
    click dockerignore "https://github.com/electricitymaps/electricitymaps-contrib/blob/master/.dockerignore"
    click parserdocker "https://github.com/electricitymaps/electricitymaps-contrib/blob/master/parsers.dockerfile"

    %% Styles
    classDef backend fill:#blue,stroke:#000,color:#fff
    classDef frontend fill:#0f0,stroke:#000,color:#000
    classDef external fill:#ccc,stroke:#000,color:#000
    classDef dev fill:#888,stroke:#000,color:#fff
```
