# weston100/ai-ecg architecture

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

- Interactive diagram: https://gitdiagram.com/weston100/ai-ecg
- Repository: https://github.com/weston100/ai-ecg

## Overview

##### Project type and purpose
- This is a Python-based open-source tool/framework for training, evaluating, and running deep‐learning models on ECG waveforms (the SEER risk model).
- There is no client/server GUI or web front end—this is a command-line ML pipeline.

##### File structure
Top-level modules:
- config.py       — central configuration (hyperparameters, file paths, task specs)
- dataset.py      — data loading & preprocessing (normalization, filtering)
- ecg.py          — orchestrator; the entry point for both train/eval modes
- model_specs.py  — network architecture definitions
- model.py        — training loop, loss, optimizer, checkpoint logic
- train.py        — script wrapper or legacy training entry (may call ecg.py)
- requirements.txt, LICENSE.txt, README.md

##### README for additional insights
- The README describes two main modes: “train” and “eval.”
- It explains how config.py drives task definitions, data paths, transforms, and save locations.

a. Main components:
1) CLI / Python entry (ecg.py/train.py)
2) Configuration manager (config.py)
3) Data pipeline (dataset.py)
4) Model builder (model_specs.py)
5) Trainer/Evaluator (model.py)
6) Persistence layer (filesystem for checkpoints, CSV outputs)
7) External dependencies (PyTorch, numpy, pandas)

b. Relationships & interactions:
- User invokes: “python3 -c ‘import ecg; ecg.ecg(mode,task)’” or train.py
→ ecg.py reads config.py (task_cfg, paths, hparams)
→ dataset.py builds DataLoader with transforms
→ model_specs.py constructs the neural net
→ model.py runs training loop or evaluation loop
→ outputs written to disk (checkpoints, .csv predictions)

c. Architectural patterns / design principles:
– Modular separation: config vs data vs model vs orchestration
– Single process pipeline; no microservices
– Clear layering: “Orchestrator → Data → Model → Persistence”
– Config-driven, pluggable tasks

d. Key technologies:
– Python 3
– PyTorch (training / inference)
– pandas / numpy (data handling, CSV I/O)
– SciPy or custom filters (notch, baseline) in dataset.py

##### Detail without overthinking
- Python module as a separate component
- Both training and evaluation flows
- Notes on where to update hyperparameters or task definitions

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestration Layer
    subgraph "Orchestration" 
        direction TB
        CLI_ecg["CLI Entry<br/>(ecg.py)"]:::orchestration
        trainScript["Legacy Training Script<br/>(train.py)"]:::orchestration
    end

    %% Configuration Manager
    config["Configuration Manager<br/>(config.py)"]:::orchestration

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        dataset["DataLoader + Transforms<br/>(dataset.py)"]:::data
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        specs["Neural Network Definitions<br/>(model_specs.py)"]:::model
        modelComp["Trainer / Evaluator<br/>(model.py)"]:::model
    end

    %% Persistence Layer
    filesystem["Filesystem Storage<br/>(Checkpoints & CSVs)"]:::storage

    %% External Dependencies
    externals["External Libraries<br/>PyTorch, numpy, pandas, SciPy"]:::external

    %% Connections
    CLI_ecg -->|"invoke train/eval"| config
    trainScript -->|"wrapper to ecg.py"| CLI_ecg

    config -->|"cfg['dataloader']"| dataset
    config -->|"cfg['model']"| specs
    config -->|"cfg['optimizer']"| modelComp

    dataset -->|"batches"| modelComp
    specs -->|"network"| modelComp

    modelComp -->|"save checkpoints & CSV"| filesystem
    filesystem -->|"load checkpoint for eval"| modelComp

    %% External deps arrows
    externals ---|provides APIs| dataset
    externals ---|provides APIs| specs
    externals ---|provides APIs| modelComp

    %% Click Events
    click CLI_ecg "https://github.com/weston100/ai-ecg/blob/main/ecg.py"
    click trainScript "https://github.com/weston100/ai-ecg/blob/main/train.py"
    click config "https://github.com/weston100/ai-ecg/blob/main/config.py"
    click dataset "https://github.com/weston100/ai-ecg/blob/main/dataset.py"
    click specs "https://github.com/weston100/ai-ecg/blob/main/model_specs.py"
    click modelComp "https://github.com/weston100/ai-ecg/blob/main/model.py"

    %% Styles
    classDef orchestration fill:#D0E6FF,stroke:#1473E6,color:#000
    classDef data fill:#DFFFD0,stroke:#4CAF50,color:#000
    classDef model fill:#FFE0B2,stroke:#FB8C00,color:#000
    classDef storage fill:#FFF9C4,stroke:#FBC02D,color:#000
    classDef external fill:#E1BEE7,stroke:#9C27B0,color:#000
```
