# rajb-1003/ecg-classification architecture

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

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

## Overview

ECG Classifier 2.0 turns uploaded or dataset ECG recordings into quality-screened, classified and explainable clinical reports. The principal inference workflow is initiated by the CLI or Streamlit UI and proceeds through loading, cleaning, quality assessment, waveform/feature analysis, classification and reporting. The repository also contains a separate configurable dataset-processing and signal-quality pipeline, plus model training and validation capabilities. Edges follow the sampled entry-point references and README workflow; unsampled internals are represented only where documented.

Main entry points: [`main.py`](https://github.com/rajb-1003/ecg-classification/blob/main/main.py) (CLI entry point), [`app.py`](https://github.com/rajb-1003/ecg-classification/blob/main/app.py) (Streamlit UI), [`core/dataset_loaders/loaders.py`](https://github.com/rajb-1003/ecg-classification/blob/main/core/dataset_loaders/loaders.py) (Dataset loaders), [`pipelines/run_pipeline.py`](https://github.com/rajb-1003/ecg-classification/blob/main/pipelines/run_pipeline.py) (Quality pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inference["ECG inference"]
  node_cli["CLI entry point<br/>[main.py]"]
  node_web["Streamlit UI<br/>[app.py]"]
  node_inputs(("ECG input"))
  node_record_loader["Record loading<br/>[ecg_loader.py]"]
end

subgraph group_analysis["Signal analysis"]
  node_cleaning["ECG cleaning<br/>[preprocessing.py]"]
  node_quality_assessment["Signal quality<br/>[signal_quality.py]"]
  node_delineation["PQRST delineation<br/>[delineation.py]"]
  node_features["Feature extraction"]
end

subgraph group_clinical["Clinical interpretation"]
  node_conduction["Conduction analysis"]
  node_rhythm["Rhythm classification"]
  node_fusion["Decision fusion<br/>[decision_fusion.py]"]
  node_clinical_rules["Clinical rules<br/>[clinical_rules.py]"]
  node_explainability["SHAP explainability<br/>[explainability.py]"]
  node_reports["Clinical reports"]
  node_visuals["ECG visualizations<br/>[ecg_visualizer.py]"]
end

subgraph group_quality["Quality pipeline"]
  node_dataset_loader["Dataset loaders<br/>[loaders.py]"]
  node_preprocessor["Production preprocessing<br/>[preprocessor.py]"]
  node_hardware_gate["Hardware sanity gate<br/>[gate.py]"]
  node_sqa_classifier["SQA classifier<br/>[classifier.py]"]
  node_core_features["Quality features<br/>[extractor.py]"]
  node_quality_reports["Quality reporting<br/>[generator.py]"]
  node_filter_config["Filter configuration<br/>[filter_config.py]"]
  node_path_config["Dataset paths<br/>[paths.py]"]
  node_pipeline["Quality pipeline<br/>[run_pipeline.py]"]
end

subgraph group_models["Models and validation"]
  node_training["Model training<br/>[train.py]"]
  node_model_artifacts[("Trained models")]
  node_evaluation["Model evaluation<br/>[evaluate.py]"]
  node_validation["Dataset validation"]
  node_external_validation["External validation"]
end

node_inputs -->|"provides records"| node_cli
node_inputs -->|"uploads ECGs"| node_web
node_cli -->|"loads records"| node_record_loader
node_cli -->|"cleans signals"| node_cleaning
node_cli -->|"assesses quality"| node_quality_assessment
node_cli -->|"detects waves"| node_delineation
node_cli -->|"extracts features"| node_features
node_cli -->|"analyzes conduction"| node_conduction
node_cli -->|"fuses decisions"| node_fusion
node_cli -->|"explains predictions"| node_explainability
node_cli -->|"generates reports"| node_reports
node_cli -->|"renders plots"| node_visuals
node_web -->|"loads records"| node_record_loader
node_web -->|"cleans signals"| node_cleaning
node_web -->|"assesses quality"| node_quality_assessment
node_web -->|"shows delineation"| node_delineation
node_web -->|"analyzes conduction"| node_conduction
node_web -->|"classifies ECG"| node_fusion
node_web -.->|"shows explanations"| node_explainability
node_web -.->|"shows report"| node_reports
node_training -->|"saves models"| node_model_artifacts
node_cli -->|"starts training"| node_training
node_cli -->|"loads models"| node_model_artifacts
node_evaluation -->|"evaluates models"| node_model_artifacts
node_fusion -.->|"applies rules"| node_clinical_rules
node_pipeline -->|"loads datasets"| node_dataset_loader
node_pipeline -->|"filters signals"| node_preprocessor
node_pipeline -->|"checks hardware"| node_hardware_gate
node_pipeline -->|"extracts features"| node_core_features
node_pipeline -->|"generates reports"| node_quality_reports
node_dataset_loader -->|"uses paths"| node_path_config
node_dataset_loader -->|"reads settings"| node_filter_config
node_preprocessor -->|"reads settings"| node_filter_config
node_preprocessor -->|"accepts records"| node_dataset_loader
node_quality_reports -->|"uses records"| node_dataset_loader
node_quality_reports -->|"uses gate results"| node_hardware_gate
node_quality_reports -->|"uses features"| node_core_features
node_quality_reports -->|"reads settings"| node_filter_config
node_validation -->|"loads datasets"| node_dataset_loader
node_validation -->|"filters signals"| node_preprocessor
node_validation -->|"checks hardware"| node_hardware_gate
node_validation -->|"extracts features"| node_core_features
node_validation -->|"classifies quality"| node_sqa_classifier
node_external_validation -->|"loads datasets"| node_dataset_loader
node_external_validation -->|"filters signals"| node_preprocessor
node_external_validation -->|"checks hardware"| node_hardware_gate
node_external_validation -->|"extracts features"| node_core_features
node_external_validation -->|"classifies quality"| node_sqa_classifier

click node_cli "https://github.com/rajb-1003/ecg-classification/blob/main/main.py"
click node_web "https://github.com/rajb-1003/ecg-classification/blob/main/app.py"
click node_record_loader "https://github.com/rajb-1003/ecg-classification/blob/main/ecg_loader.py"
click node_cleaning "https://github.com/rajb-1003/ecg-classification/blob/main/preprocessing.py"
click node_quality_assessment "https://github.com/rajb-1003/ecg-classification/blob/main/signal_quality.py"
click node_delineation "https://github.com/rajb-1003/ecg-classification/blob/main/delineation.py"
click node_features "https://github.com/rajb-1003/ecg-classification/blob/main/feature_extraction.py"
click node_conduction "https://github.com/rajb-1003/ecg-classification/blob/main/conduction_analysis.py"
click node_rhythm "https://github.com/rajb-1003/ecg-classification/blob/main/rhythm_classifier.py"
click node_fusion "https://github.com/rajb-1003/ecg-classification/blob/main/decision_fusion.py"
click node_clinical_rules "https://github.com/rajb-1003/ecg-classification/blob/main/clinical_rules.py"
click node_explainability "https://github.com/rajb-1003/ecg-classification/blob/main/explainability.py"
click node_reports "https://github.com/rajb-1003/ecg-classification/blob/main/report_generator.py"
click node_visuals "https://github.com/rajb-1003/ecg-classification/blob/main/ecg_visualizer.py"
click node_training "https://github.com/rajb-1003/ecg-classification/blob/main/train.py"
click node_evaluation "https://github.com/rajb-1003/ecg-classification/blob/main/evaluate.py"
click node_dataset_loader "https://github.com/rajb-1003/ecg-classification/blob/main/core/dataset_loaders/loaders.py"
click node_preprocessor "https://github.com/rajb-1003/ecg-classification/blob/main/core/preprocessing/preprocessor.py"
click node_hardware_gate "https://github.com/rajb-1003/ecg-classification/blob/main/core/hardware_gate/gate.py"
click node_sqa_classifier "https://github.com/rajb-1003/ecg-classification/blob/main/core/sqa/classifier.py"
click node_core_features "https://github.com/rajb-1003/ecg-classification/blob/main/core/feature_extraction/extractor.py"
click node_quality_reports "https://github.com/rajb-1003/ecg-classification/blob/main/core/reporting/generator.py"
click node_filter_config "https://github.com/rajb-1003/ecg-classification/blob/main/config/filter_config.py"
click node_path_config "https://github.com/rajb-1003/ecg-classification/blob/main/config/paths.py"
click node_pipeline "https://github.com/rajb-1003/ecg-classification/blob/main/pipelines/run_pipeline.py"
click node_validation "https://github.com/rajb-1003/ecg-classification/blob/main/pipelines/run_batch_validation.py"
click node_external_validation "https://github.com/rajb-1003/ecg-classification/blob/main/pipelines/run_external_validation.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_web,node_inputs,node_record_loader toneBlue
class node_cleaning,node_quality_assessment,node_delineation,node_features toneAmber
class node_conduction,node_rhythm,node_fusion,node_clinical_rules,node_explainability,node_reports,node_visuals toneMint
class node_dataset_loader,node_preprocessor,node_hardware_gate,node_sqa_classifier,node_core_features,node_quality_reports,node_filter_config,node_path_config,node_pipeline toneRose
class node_training,node_model_artifacts,node_evaluation,node_validation,node_external_validation toneIndigo
```

## Components

### ECG inference

- [CLI entry point](https://github.com/rajb-1003/ecg-classification/blob/main/main.py): `main.py`
- [Streamlit UI](https://github.com/rajb-1003/ecg-classification/blob/main/app.py): `app.py`
- **ECG input**
- [Record loading](https://github.com/rajb-1003/ecg-classification/blob/main/ecg_loader.py): `ecg_loader.py`

### Signal analysis

- [ECG cleaning](https://github.com/rajb-1003/ecg-classification/blob/main/preprocessing.py): `preprocessing.py`
- [Signal quality](https://github.com/rajb-1003/ecg-classification/blob/main/signal_quality.py): `signal_quality.py`
- [PQRST delineation](https://github.com/rajb-1003/ecg-classification/blob/main/delineation.py): `delineation.py`
- [Feature extraction](https://github.com/rajb-1003/ecg-classification/blob/main/feature_extraction.py): `feature_extraction.py`

### Clinical interpretation

- [Conduction analysis](https://github.com/rajb-1003/ecg-classification/blob/main/conduction_analysis.py): `conduction_analysis.py`
- [Rhythm classification](https://github.com/rajb-1003/ecg-classification/blob/main/rhythm_classifier.py): `rhythm_classifier.py`
- [Decision fusion](https://github.com/rajb-1003/ecg-classification/blob/main/decision_fusion.py): `decision_fusion.py`
- [Clinical rules](https://github.com/rajb-1003/ecg-classification/blob/main/clinical_rules.py): `clinical_rules.py`
- [SHAP explainability](https://github.com/rajb-1003/ecg-classification/blob/main/explainability.py): `explainability.py`
- [Clinical reports](https://github.com/rajb-1003/ecg-classification/blob/main/report_generator.py): `report_generator.py`
- [ECG visualizations](https://github.com/rajb-1003/ecg-classification/blob/main/ecg_visualizer.py): `ecg_visualizer.py`

### Quality pipeline

- [Dataset loaders](https://github.com/rajb-1003/ecg-classification/blob/main/core/dataset_loaders/loaders.py): `core/dataset_loaders/loaders.py`
- [Production preprocessing](https://github.com/rajb-1003/ecg-classification/blob/main/core/preprocessing/preprocessor.py): `core/preprocessing/preprocessor.py`
- [Hardware sanity gate](https://github.com/rajb-1003/ecg-classification/blob/main/core/hardware_gate/gate.py): `core/hardware_gate/gate.py`
- [SQA classifier](https://github.com/rajb-1003/ecg-classification/blob/main/core/sqa/classifier.py): `core/sqa/classifier.py`
- [Quality features](https://github.com/rajb-1003/ecg-classification/blob/main/core/feature_extraction/extractor.py): `core/feature_extraction/extractor.py`
- [Quality reporting](https://github.com/rajb-1003/ecg-classification/blob/main/core/reporting/generator.py): `core/reporting/generator.py`
- [Filter configuration](https://github.com/rajb-1003/ecg-classification/blob/main/config/filter_config.py): `config/filter_config.py`
- [Dataset paths](https://github.com/rajb-1003/ecg-classification/blob/main/config/paths.py): `config/paths.py`
- [Quality pipeline](https://github.com/rajb-1003/ecg-classification/blob/main/pipelines/run_pipeline.py): `pipelines/run_pipeline.py`

### Models and validation

- [Model training](https://github.com/rajb-1003/ecg-classification/blob/main/train.py): `train.py`
- **Trained models**
- [Model evaluation](https://github.com/rajb-1003/ecg-classification/blob/main/evaluate.py): `evaluate.py`
- [Dataset validation](https://github.com/rajb-1003/ecg-classification/blob/main/pipelines/run_batch_validation.py): `pipelines/run_batch_validation.py`
- [External validation](https://github.com/rajb-1003/ecg-classification/blob/main/pipelines/run_external_validation.py): `pipelines/run_external_validation.py`

## Connections

- ECG input → CLI entry point: provides records
- ECG input → Streamlit UI: uploads ECGs
- CLI entry point → Record loading: loads records (evidence: `main.py`)
- CLI entry point → ECG cleaning: cleans signals (evidence: `main.py`)
- CLI entry point → Signal quality: assesses quality (evidence: `main.py`)
- CLI entry point → PQRST delineation: detects waves (evidence: `main.py`)
- CLI entry point → Feature extraction: extracts features (evidence: `main.py`)
- CLI entry point → Conduction analysis: analyzes conduction (evidence: `main.py`)
- CLI entry point → Decision fusion: fuses decisions (evidence: `main.py`)
- CLI entry point → SHAP explainability: explains predictions (evidence: `main.py`)
- CLI entry point → Clinical reports: generates reports (evidence: `main.py`)
- CLI entry point → ECG visualizations: renders plots
- Streamlit UI → Record loading: loads records (evidence: `app.py`)
- Streamlit UI → ECG cleaning: cleans signals (evidence: `app.py`)
- Streamlit UI → Signal quality: assesses quality (evidence: `app.py`)
- Streamlit UI → PQRST delineation: shows delineation (evidence: `app.py`)
- Streamlit UI → Conduction analysis: analyzes conduction (evidence: `app.py`)
- Streamlit UI → Decision fusion: classifies ECG (evidence: `app.py`)
- Streamlit UI → SHAP explainability: shows explanations (evidence: `app.py`)
- Streamlit UI → Clinical reports: shows report
- Model training → Trained models: saves models
- CLI entry point → Model training: starts training (evidence: `main.py`)
- CLI entry point → Trained models: loads models
- Model evaluation → Trained models: evaluates models
- Decision fusion → Clinical rules: applies rules
- Quality pipeline → Dataset loaders: loads datasets (evidence: `pipelines/run_pipeline.py`)
- Quality pipeline → Production preprocessing: filters signals (evidence: `pipelines/run_pipeline.py`)
- Quality pipeline → Hardware sanity gate: checks hardware (evidence: `pipelines/run_pipeline.py`)
- Quality pipeline → Quality features: extracts features (evidence: `pipelines/run_pipeline.py`)
- Quality pipeline → Quality reporting: generates reports (evidence: `pipelines/run_pipeline.py`)
- Dataset loaders → Dataset paths: uses paths (evidence: `core/dataset_loaders/loaders.py`)
- Dataset loaders → Filter configuration: reads settings (evidence: `core/dataset_loaders/loaders.py`)
- Production preprocessing → Filter configuration: reads settings (evidence: `core/preprocessing/preprocessor.py`)
- Production preprocessing → Dataset loaders: accepts records (evidence: `core/preprocessing/preprocessor.py`)
- Quality reporting → Dataset loaders: uses records (evidence: `core/reporting/generator.py`)
- Quality reporting → Hardware sanity gate: uses gate results (evidence: `core/reporting/generator.py`)
- Quality reporting → Quality features: uses features (evidence: `core/reporting/generator.py`)
- Quality reporting → Filter configuration: reads settings (evidence: `core/reporting/generator.py`)
- Dataset validation → Dataset loaders: loads datasets (evidence: `pipelines/run_batch_validation.py`)
- Dataset validation → Production preprocessing: filters signals (evidence: `pipelines/run_batch_validation.py`)
- Dataset validation → Hardware sanity gate: checks hardware (evidence: `pipelines/run_batch_validation.py`)
- Dataset validation → Quality features: extracts features (evidence: `pipelines/run_batch_validation.py`)
- Dataset validation → SQA classifier: classifies quality (evidence: `pipelines/run_batch_validation.py`)
- External validation → Dataset loaders: loads datasets (evidence: `pipelines/run_external_validation.py`)
- External validation → Production preprocessing: filters signals (evidence: `pipelines/run_external_validation.py`)
- External validation → Hardware sanity gate: checks hardware (evidence: `pipelines/run_external_validation.py`)
- External validation → Quality features: extracts features (evidence: `pipelines/run_external_validation.py`)
- External validation → SQA classifier: classifies quality (evidence: `pipelines/run_external_validation.py`)
