# lxdv/ecg-classification architecture

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

- Interactive diagram: https://gitdiagram.com/lxdv/ecg-classification
- Repository: https://github.com/lxdv/ecg-classification

## Overview

##### Project type and purpose
-  This is a research-oriented, config-driven, full-stack Python/PyTorch pipeline for training, validating, and running inference on CNN models (1D and 2D) for ECG arrhythmia classification.
-  It supports three modes: Training (`train.py`), Validation/Inference (`inference.py`), and End-to-End Pipeline (`pipeline.py`), all driven by JSON configs.

##### Main components
a.  Data Sources
- MIT-BIH raw ECG files (`mit-bih/*.dat`,`*.hea`,`*.atr`)
- Pre-generated experiment datasets (`experiments/...`)
b.  Data Preparation
- Scripts (`scripts/`)
– `dataset-generation-pool.py`,
– `annotation-generation-1d.py`,
– `annotation-generation-2d.py`
- Outputs intermediate data artifacts (e.g., `.npy`, `.png` for 2D)
c.  Configuration Layer
- JSON configs under `configs/training/`, `configs/inference/`, `configs/pipelines/`
- Single `config.json` format for each mode
d.  Core Libraries
- Dataloaders (`dataloaders/dataset1d.py`, `dataset2d.py`): load data into PyTorch Datasets/DataLoaders
- Models (`models/models1d.py`, `models/models2d.py`): instantiate CNN architectures (ResNet34, EfficientNet, etc.)
- Trainers (`trainers/`): `BaseTrainer` and concrete trainers to drive `forward`/`backward` loops
- Runners (`runners/`): `BaseRunner` and inference runners that wrap a model+loader to produce outputs
e.  Entry-point Scripts
- `train.py` – loads config → builds Trainer → kicks off training → saves checkpoints and logs
- `inference.py` – loads config → builds Runner → runs validation/inference → outputs metrics
- `pipeline.py` – loads config → builds Pipeline → runs full workflow → saves HTML results
f.  Utilities & Notebooks
- `utils/network_utils.py` for model utilities
- Jupyter Notebooks (`notebooks/`) for EDA, confusion matrices
g.  CI/CD
- GitHub Actions workflows under `.github/workflows/` automatically install, train, and badge models

##### Relationships & Data Flow
-  Start: Raw ECG data → *scripts* → generated dataset files
-  Config JSON → passed to Entry script (`train.py`/`inference.py`/`pipeline.py`)
-  Script reads config → instantiates Dataloader ←→ Model ←→ Trainer/Runner/Pipeline
-  Trainer writes: checkpoints, logs, metrics
-  Runner/Pipeline writes: predictions, visualizations, HTML reports
-  CI workflows trigger scripts per commit/PR

##### Architectural Patterns & Principles
-  “Config-principle”: all params and paths driven by JSON, no hard-coding
-  Modular design: clear separation of concerns (data, models, training, pipelines)
-  Base classes + inheritance (e.g., `BaseTrainer`, `BaseRunner`, `BasePipeline`)
-  Reusable components: the same dataloaders/models are used across training and inference

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top: CI/CD
    CI["GitHub Actions"]:::external

    %% Left: Data Sources and Preparation
    subgraph "Data Sources & Preparation"
        DS["MIT-BIH Raw ECG"]:::data
        click DS "https://github.com/lxdv/ecg-classification/tree/master/mit-bih/"
        SP1["annotation-generation-1d.py"]:::process
        click SP1 "https://github.com/lxdv/ecg-classification/blob/master/scripts/annotation-generation-1d.py"
        SP2["annotation-generation-2d.py"]:::process
        click SP2 "https://github.com/lxdv/ecg-classification/blob/master/scripts/annotation-generation-2d.py"
        SP3["dataset-generation-pool.py"]:::process
        click SP3 "https://github.com/lxdv/ecg-classification/blob/master/scripts/dataset-generation-pool.py"
        GD["Generated Dataset"]:::data
    end

    %% Center: Configs and Entry Points
    subgraph "Configuration & Entry Scripts"
        CFG_T["Training Configs"]:::data
        click CFG_T "https://github.com/lxdv/ecg-classification/tree/master/configs/training/"
        CFG_I["Inference Config"]:::data
        click CFG_I "https://github.com/lxdv/ecg-classification/blob/master/configs/inference/config.json"
        CFG_P["Pipeline Config"]:::data
        click CFG_P "https://github.com/lxdv/ecg-classification/blob/master/configs/pipelines/config.json"
        TS["train.py"]:::process
        click TS "https://github.com/lxdv/ecg-classification/blob/master/train.py"
        IS["inference.py"]:::process
        click IS "https://github.com/lxdv/ecg-classification/blob/master/inference.py"
        PS["pipeline.py"]:::process
        click PS "https://github.com/lxdv/ecg-classification/blob/master/pipeline.py"
    end

    %% Core Modules
    subgraph "Core Modules"
        subgraph "Dataloaders"
            DL1["Dataset1D Loader"]:::code
            click DL1 "https://github.com/lxdv/ecg-classification/blob/master/dataloaders/dataset1d.py"
            DL2["Dataset2D Loader"]:::code
            click DL2 "https://github.com/lxdv/ecg-classification/blob/master/dataloaders/dataset2d.py"
        end
        subgraph "Models"
            M1["1D CNN Architectures"]:::code
            click M1 "https://github.com/lxdv/ecg-classification/blob/master/models/models1d.py"
            M2["2D CNN Architectures"]:::code
            click M2 "https://github.com/lxdv/ecg-classification/blob/master/models/models2d.py"
        end
        subgraph "Trainers"
            BT["BaseTrainer"]:::code
            click BT "https://github.com/lxdv/ecg-classification/blob/master/trainers/base_trainer.py"
            CT["Concrete Trainers"]:::code
            click CT "https://github.com/lxdv/ecg-classification/blob/master/trainers/trainers.py"
        end
        subgraph "Runners"
            BR["BaseRunner"]:::code
            click BR "https://github.com/lxdv/ecg-classification/blob/master/runners/base_runner.py"
            IR["Inference Runners"]:::code
            click IR "https://github.com/lxdv/ecg-classification/blob/master/runners/runners.py"
        end
        subgraph "Pipelines"
            BP["BasePipeline"]:::code
            click BP "https://github.com/lxdv/ecg-classification/blob/master/pipelines/base_pipeline.py"
            EP["End-to-End Pipelines"]:::code
            click EP "https://github.com/lxdv/ecg-classification/blob/master/pipelines/pipelines.py"
        end
    end

    %% Utilities & Notebooks
    subgraph "Utilities & Notebooks"
        UTIL["Network Utilities"]:::code
        click UTIL "https://github.com/lxdv/ecg-classification/blob/master/utils/network_utils.py"
        NB1["eda.ipynb"]:::process
        click NB1 "https://github.com/lxdv/ecg-classification/blob/master/notebooks/eda.ipynb"
        NB2["confusion-matrix.ipynb"]:::process
        click NB2 "https://github.com/lxdv/ecg-classification/blob/master/notebooks/confusion-matrix.ipynb"
    end

    %% Artifacts
    subgraph "Artifacts"
        CKPT["Model Checkpoints"]:::data
        MET["Metrics"]:::data
        PRED["Predictions"]:::data
        VIS["Visualizations"]:::data
        HTML["HTML Reports"]:::data
    end

    %% Connections
    CI -->|triggers| TS
    CI -->|triggers| IS
    CI -->|triggers| PS

    DS --> SP1
    DS --> SP2
    DS --> SP3
    SP1 --> GD
    SP2 --> GD
    SP3 --> GD

    GD --> TS
    GD --> IS
    GD --> PS

    CFG_T --> TS
    CFG_I --> IS
    CFG_P --> PS

    TS --> DL1
    TS --> DL2
    TS --> BT
    TS --> CT
    TS --> UTIL

    IS --> DL1
    IS --> DL2
    IS --> IR
    IS --> BR

    PS --> DL1
    PS --> DL2
    PS --> EP
    PS --> BP

    DL1 --> M1
    DL2 --> M2

    M1 --> BT
    M2 --> BT
    M1 --> IR
    M2 --> IR
    M1 --> EP
    M2 --> EP

    BT --> CKPT
    BT --> MET
    IR --> PRED
    IR --> VIS
    EP --> HTML
    EP --> VIS

    UTIL --> BT
    UTIL --> IR
    UTIL --> EP

    NB1 --- MET
    NB2 --- VIS

    %% Styles
    classDef code fill:#cfe2f3,stroke:#333,stroke-width:1px
    classDef data fill:#d9ead3,stroke:#333,stroke-width:1px
    classDef process fill:#f9cb9c,stroke:#333,stroke-width:1px
    classDef external fill:#d9d9d9,stroke:#333,stroke-width:1px
```
