# flipflop133/energytrackr architecture

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

- Interactive diagram: https://gitdiagram.com/flipflop133/energytrackr
- Repository: https://github.com/flipflop133/energytrackr

## Overview

##### Project Type & Purpose
- Type: A command-line tool / open-source library (Python)
- Purpose: Orchestrates a pluggable pipeline of “stages” to measure energy consumption (via Intel RAPL or perf) across Git commits, then outputs CSV data and automated plots.

##### Main Components
A. CLI & Command Dispatcher
– `main.py` → Parses args (via `utils/args_parser.py`) → Delegates to `commands/dispatcher.py`
B. Configuration Subsystem
– `config/loader.py` loads JSON/YAML → `config/config_model.py` (pydantic) → `config/config_store.py`
C. Pipeline Orchestrator
– `pipeline/pipeline.py`: `Pipeline` class reads `execution_plan` → instantiates `PipelineStage` objects → coordinates execution
– `stage_interface.py`: Defines the interface for all stages
D. Core & Custom Stages (Plugin Points)
– Core stages (`pipeline/core_stages/…`): checkout, pre-build, build, measure, regression check, post-test, etc.
– Custom stages (`pipeline/custom_stages/…`): e.g. `java_setup_stage.py`
E. Measurement Engine
– Under the measure stage: invokes external tools (GitPython, perf, Intel RAPL); writes raw energy readings
F. Data Persistence
– CSV writer (built into pipeline stages) → `sorted.csv`, metadata
G. Plotting Subsystem
– `plot/pipeline.py` loads CSV → passes through:
- Data transforms (`plot/builtin_data_transforms/…`)
- Plot object registry & renderers (`plot/builtin_plot_objects/…`)
- Page sections & templates (`plot/builtin_page_sections/…`)
- Core loader & context (`plot/core/…`)
– Outputs PNG/HTML via `matplotlib` + JS assets
H. Utilities
– `utils/logger.py`, `git_utils.py`, `sort.py`, generic helpers
I. External Dependencies & Tools
– Git (GitPython), Python (≥3.13), perf or RAPL, matplotlib, ruptures, pydantic

##### Component Relationships & Data Flow
- CLI → Dispatcher → Config Loader → Pipeline Orchestrator
- Pipeline → executes sequence of Stage instances → each stage may invoke Git, build tools, measure tools → writes intermediate results (CSV)
- Once pipeline completes → Plotting Subsystem ingests CSV → runs transforms → assembles page → dumps plots
- Utilities provide cross-cutting support (logging, error handling, sorting)

##### Architectural Patterns & Design Principles
- Modular “PipelineStage” interface (Strategy/Plugin pattern)
- Registry pattern for plot types
- Layered: CLI → Core engine → Plugins → I/O (CSV/plots)
- Single Responsibility: each stage does one thing (checkout, build, measure, etc.)
- Configuration-driven execution plan (Pydantic models enforce schema)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        Main["main.py"]:::cli
        ArgsParser["args_parser.py"]:::cli
        Dispatcher["dispatcher.py"]:::cli
    end

    %% Configuration Layer
    subgraph "Configuration Subsystem"
        direction TB
        ConfigLoader["loader.py"]:::config
        ConfigModel["config_model.py"]:::config
        ConfigStore["config_store.py"]:::config
    end

    %% Pipeline Core
    subgraph "Pipeline Core"
        direction TB
        Pipeline["pipeline.py"]:::pipeline
        StageInterface["stage_interface.py"]:::pipeline
    end

    %% Core Pipeline Stages
    subgraph "Core Pipeline Stages"
        direction TB
        CheckoutStage["checkout_stage.py"]:::stage
        PreBuildStage["pre_build_stage.py"]:::stage
        BuildStage["build_stage.py"]:::stage
        MeasureStage["measure_stage.py"]:::stage
        FilterStage["filter_and_regression_stage.py"]:::stage
        StabilityStage["stability_check_stage.py"]:::stage
        TempCheckStage["temperature_check_stage.py"]:::stage
        PerfVerifyStage["verify_perf_stage.py"]:::stage
        PostTestStage["post_test_stage.py"]:::stage
        SetDirStage["set_directory_stage.py"]:::stage
        CopyDirStage["copy_directory_stage.py"]:::stage
    end

    CustomStage["java_setup_stage.py"]:::stage

    %% Data Persistence
    CSVStore["CSV Output"]:::output

    %% Plotting Subsystem
    subgraph "Plotting Subsystem"
        direction TB
        PlotPipeline["pipeline.py"]:::plot
        PlotConfig["config.py"]:::plot
        CoreLoader["loader.py"]:::plot
        CoreContext["context.py"]:::plot
        CoreInterfaces["interfaces.py"]:::plot
        DataTransforms["builtin_data_transforms"]:::plot
        PageSections["builtin_page_sections"]:::plot
        PlotObjects["builtin_plot_objects"]:::plot
        PlotRegistry["registry.py"]:::plot
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        Logger["logger.py"]:::util
        Exceptions["exceptions.py"]:::util
        Utils["utils.py"]:::util
        GitUtils["git_utils.py"]:::util
        Sort["sort.py"]:::util
    end

    %% External Tools
    subgraph "External Tools"
        direction TB
        Git["Git / GitPython"]:::external
        PerfRAPL["perf / RAPL"]:::external
        Matplotlib["matplotlib"]:::external
        Ruptures["ruptures"]:::external
        Pydantic["pydantic"]:::external
    end

    %% Outputs
    CSVOut["sorted.csv & metadata"]:::output
    PlotOut["PNG / HTML"]:::output

    %% Flow Connections
    Main --> ArgsParser
    Main --> Dispatcher
    Dispatcher --> ConfigLoader
    ConfigLoader --> ConfigModel
    ConfigModel --> ConfigStore
    ConfigStore --> Pipeline
    Pipeline --> StageInterface
    Pipeline --> CheckoutStage
    Pipeline --> PreBuildStage
    Pipeline --> BuildStage
    Pipeline --> MeasureStage
    Pipeline --> FilterStage
    Pipeline --> StabilityStage
    Pipeline --> TempCheckStage
    Pipeline --> PerfVerifyStage
    Pipeline --> PostTestStage
    Pipeline --> SetDirStage
    Pipeline --> CopyDirStage
    Pipeline --> CustomStage
    MeasureStage --> GitUtils
    MeasureStage --> PerfRAPL
    CheckoutStage --> Git
    CopiedStage ---|plugin| CustomStage
    BuildStage --> GitUtils
    FilterStage --> Sort
    PostTestStage --> CSVStore
    CSVStore --> CSVOut
    CSVStore --> PlotPipeline
    PlotPipeline --> PlotConfig
    PlotPipeline --> CoreLoader
    CoreLoader --> CoreContext
    CoreContext --> CoreInterfaces
    CoreInterfaces --> DataTransforms
    DataTransforms --> PlotObjects
    PlotObjects --> PlotRegistry
    PlotRegistry --> PlotOut

    %% Utilities Connections
    Logger --- Pipeline
    Utils --- Pipeline

    %% External Dependencies
    Pipeline --> Git
    Pipeline --> PerfRAPL
    PlotPipeline --> Matplotlib
    PlotPipeline --> Ruptures
    ConfigModel --> Pydantic

    %% Click Events
    click Main "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/main.py"
    click ArgsParser "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/utils/args_parser.py"
    click Dispatcher "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/commands/dispatcher.py"
    click ConfigLoader "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/config/loader.py"
    click ConfigModel "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/config/config_model.py"
    click ConfigStore "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/config/config_store.py"
    click Pipeline "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/pipeline/pipeline.py"
    click StageInterface "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/pipeline/stage_interface.py"
    click CheckoutStage "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/pipeline/core_stages/checkout_stage.py"
    click PreBuildStage "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/pipeline/core_stages/pre_build_stage.py"
    click BuildStage "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/pipeline/core_stages/build_stage.py"
    click MeasureStage "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/pipeline/core_stages/measure_stage.py"
    click FilterStage "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/pipeline/core_stages/filter_and_regression_stage.py"
    click StabilityStage "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/pipeline/core_stages/stability_check_stage.py"
    click TempCheckStage "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/pipeline/core_stages/temperature_check_stage.py"
    click PerfVerifyStage "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/pipeline/core_stages/verify_perf_stage.py"
    click PostTestStage "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/pipeline/core_stages/post_test_stage.py"
    click SetDirStage "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/pipeline/core_stages/set_directory_stage.py"
    click CopyDirStage "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/pipeline/core_stages/copy_directory_stage.py"
    click CustomStage "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/pipeline/custom_stages/java_setup_stage.py"
    click GitUtils "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/utils/git_utils.py"
    click Sort "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/utils/sort.py"
    click PlotPipeline "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/plot/pipeline.py"
    click PlotConfig "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/plot/config.py"
    click CoreLoader "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/plot/core/loader.py"
    click CoreContext "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/plot/core/context.py"
    click CoreInterfaces "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/plot/core/interfaces.py"
    click DataTransforms "https://github.com/flipflop133/energytrackr/tree/main/src/energytrackr/plot/builtin_data_transforms"
    click PageSections "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/plot/builtin_page_sections/base.py"
    click PlotObjects "https://github.com/flipflop133/energytrackr/tree/main/src/energytrackr/plot/builtin_plot_objects"
    click PlotRegistry "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/plot/builtin_plots/registry.py"
    click Logger "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/utils/logger.py"
    click Exceptions "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/utils/exceptions.py"
    click Utils "https://github.com/flipflop133/energytrackr/blob/main/src/energytrackr/utils/utils.py"

    %% Styles
    classDef cli fill:#D6E9FF,stroke:#2B6CB0,color:#2B6CB0;
    classDef config fill:#DFFFE0,stroke:#38A169,color:#38A169;
    classDef pipeline fill:#E6FFFA,stroke:#2C7A7B,color:#2C7A7B;
    classDef stage fill:#FFF5E6,stroke:#DD6B20,color:#DD6B20;
    classDef plot fill:#FFF0F6,stroke:#B83280,color:#B83280;
    classDef util fill:#F0F4F8,stroke:#4A5568,color:#4A5568;
    classDef external fill:#FFE6E6,stroke:#C53030,color:#C53030;
    classDef output fill:#EBF4FF,stroke:#2B6CB0,color:#2B6CB0;
```
