# prabhu-omkar/cardioedge-esp32 architecture

> Architecture diagram of the GitHub repository prabhu-omkar/cardioedge-esp32, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prabhu-omkar/cardioedge-esp32
- Repository: https://github.com/prabhu-omkar/cardioedge-esp32

## Overview

CardioEdge-ESP32 is an offline ECG monitor and development pipeline: the device samples live or demo ECG, processes and quality-gates beats, classifies accepted beats, then presents rolling verdicts and alerts. In parallel, Python prepares patient-wise datasets using the same DSP core, trains CNN and Random Forest models, and evaluates them. The README documents the end-to-end behavior; source excerpts show key firmware, DSP, dataset, and training details, but not every runtime call, so some links rely on documentation.

Main entry points: [`firmware/src/main.cpp`](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/src/main.cpp) (ESP32 Runtime), [`ml/core.py`](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/ml/core.py) (Python DSP Binding), [`ml/common.py`](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/ml/common.py) (ML Data Utilities), [`firmware/lib/ecg_core/ecg_core.cpp`](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/lib/ecg_core/ecg_core.cpp) (ECG DSP Core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_device["ESP32 Monitoring"]
  node_esp32["ESP32 Runtime<br/>[main.cpp]"]
  node_demo["Demo Clips<br/>[demo_clips.h]"]
  node_state["Live State<br/>[state.h]"]
end

subgraph group_dsp["Signal Processing"]
  node_core["ECG DSP Core<br/>[ecg_core.cpp]"]
  node_config["DSP Contracts<br/>[ecg_config.h]"]
  node_features["Beat Features<br/>[ecg_core.cpp]"]
  node_sqa["Signal Quality Gate<br/>[ecg_core.cpp]"]
  node_rhythm["Rhythm and HRV<br/>[ecg_core.cpp]"]
end

subgraph group_models["Classification"]
  node_classify["Dual Classifiers<br/>[classifiers.cpp]"]
  node_cnn["Int8 CNN<br/>[model_cnn.h]"]
  node_rf["Random Forest<br/>[rf_predict.h]"]
end

subgraph group_ml["Data and Evaluation"]
  node_dataset["Patient-wise Dataset<br/>[dataset.py]"]
  node_pycore["Python DSP Binding<br/>[core.py]"]
  node_common["ML Data Utilities<br/>[common.py]"]
  node_traincnn["CNN Training<br/>[train_cnn.py]"]
  node_trainrf["RF Training<br/>[train_rf.py]"]
  node_evaluate["Model Evaluation<br/>[evaluate.py]"]
  node_capture["Capture Evaluation<br/>[eval_capture.py]"]
  node_qrs["QRS Evaluation<br/>[eval_qrs.py]"]
  node_sqa_eval["SQA Evaluation<br/>[sqa_eval.py]"]
end

subgraph group_presentation["User Outputs"]
  node_oled["OLED Display<br/>[display.cpp]"]
  node_dashboard["Phone Dashboard<br/>[webui.cpp]"]
  node_html["Dashboard Page<br/>[dashboard_html.h]"]
  node_alerts["Buzzer and LED<br/>[main.cpp]"]
end

node_electrodes(("ECG Front End"))
node_physionet[("ECG Databases")]
node_user(("Monitor User"))

node_electrodes -->|"supplies samples"| node_esp32
node_demo -->|"provides clips"| node_esp32
node_esp32 -->|"streams samples"| node_core
node_core -->|"assesses quality"| node_sqa
node_core -->|"extracts beats"| node_features
node_sqa -->|"gates classification"| node_features
node_esp32 -->|"classifies beat"| node_classify
node_classify -->|"runs CNN"| node_cnn
node_classify -->|"runs forest"| node_rf
node_esp32 -->|"applies rhythm logic"| node_rhythm
node_esp32 -->|"updates snapshot"| node_state
node_esp32 -->|"refreshes display"| node_oled
node_esp32 -->|"serves dashboard"| node_dashboard
node_dashboard -->|"serves page"| node_html
node_esp32 -->|"drives alarm"| node_alerts
node_user -->|"views verdicts"| node_oled
node_user -->|"views live data"| node_dashboard
node_physionet -->|"provides records"| node_dataset
node_dataset -->|"processes recordings"| node_pycore
node_pycore -->|"calls shared DSP"| node_core
node_dataset -->|"writes split data"| node_common
node_common -->|"loads training splits"| node_traincnn
node_common -->|"loads training splits"| node_trainrf
node_common -->|"loads test splits"| node_evaluate
node_traincnn -->|"exports device model"| node_cnn
node_trainrf -->|"exports forest model"| node_rf
node_evaluate -->|"measures gate effects"| node_sqa_eval
node_evaluate -->|"evaluates inference"| node_pycore
node_capture -->|"evaluates captures"| node_pycore
node_qrs -->|"evaluates detection"| node_pycore

click node_esp32 "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/src/main.cpp"
click node_demo "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/src/demo_clips.h"
click node_core "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/lib/ecg_core/ecg_core.cpp"
click node_config "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/lib/ecg_core/ecg_config.h"
click node_features "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/lib/ecg_core/ecg_core.cpp"
click node_sqa "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/lib/ecg_core/ecg_core.cpp"
click node_classify "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/src/classifiers.cpp"
click node_cnn "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/src/model_cnn.h"
click node_rf "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/src/rf_predict.h"
click node_rhythm "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/lib/ecg_core/ecg_core.cpp"
click node_state "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/src/state.h"
click node_oled "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/src/display.cpp"
click node_dashboard "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/src/webui.cpp"
click node_html "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/src/dashboard_html.h"
click node_alerts "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/src/main.cpp"
click node_dataset "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/ml/dataset.py"
click node_pycore "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/ml/core.py"
click node_common "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/ml/common.py"
click node_traincnn "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/ml/train_cnn.py"
click node_trainrf "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/ml/train_rf.py"
click node_evaluate "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/ml/evaluate.py"
click node_capture "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/ml/eval_capture.py"
click node_qrs "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/ml/eval_qrs.py"
click node_sqa_eval "https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/ml/sqa_eval.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_esp32,node_demo,node_state,node_user toneBlue
class node_core,node_config,node_features,node_sqa,node_rhythm,node_physionet toneAmber
class node_classify,node_cnn,node_rf toneMint
class node_dataset,node_pycore,node_common,node_traincnn,node_trainrf,node_evaluate,node_capture,node_qrs,node_sqa_eval toneRose
class node_oled,node_dashboard,node_html,node_alerts,node_electrodes toneIndigo
```

## Components

### ESP32 Monitoring

- [ESP32 Runtime](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/src/main.cpp): `firmware/src/main.cpp`
- [Demo Clips](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/src/demo_clips.h): `firmware/src/demo_clips.h`
- [Live State](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/src/state.h): `firmware/src/state.h`

### Signal Processing

- [ECG DSP Core](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/lib/ecg_core/ecg_core.cpp): `firmware/lib/ecg_core/ecg_core.cpp`
- [DSP Contracts](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/lib/ecg_core/ecg_config.h): `firmware/lib/ecg_core/ecg_config.h`
- [Beat Features](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/lib/ecg_core/ecg_core.cpp): `firmware/lib/ecg_core/ecg_core.cpp`
- [Signal Quality Gate](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/lib/ecg_core/ecg_core.cpp): `firmware/lib/ecg_core/ecg_core.cpp`
- [Rhythm and HRV](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/lib/ecg_core/ecg_core.cpp): `firmware/lib/ecg_core/ecg_core.cpp`

### Classification

- [Dual Classifiers](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/src/classifiers.cpp): `firmware/src/classifiers.cpp`
- [Int8 CNN](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/src/model_cnn.h): `firmware/src/model_cnn.h`
- [Random Forest](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/src/rf_predict.h): `firmware/src/rf_predict.h`

### Data and Evaluation

- [Patient-wise Dataset](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/ml/dataset.py): `ml/dataset.py`
- [Python DSP Binding](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/ml/core.py): `ml/core.py`
- [ML Data Utilities](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/ml/common.py): `ml/common.py`
- [CNN Training](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/ml/train_cnn.py): `ml/train_cnn.py`
- [RF Training](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/ml/train_rf.py): `ml/train_rf.py`
- [Model Evaluation](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/ml/evaluate.py): `ml/evaluate.py`
- [Capture Evaluation](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/ml/eval_capture.py): `ml/eval_capture.py`
- [QRS Evaluation](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/ml/eval_qrs.py): `ml/eval_qrs.py`
- [SQA Evaluation](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/ml/sqa_eval.py): `ml/sqa_eval.py`

### User Outputs

- [OLED Display](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/src/display.cpp): `firmware/src/display.cpp`
- [Phone Dashboard](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/src/webui.cpp): `firmware/src/webui.cpp`
- [Dashboard Page](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/src/dashboard_html.h): `firmware/src/dashboard_html.h`
- [Buzzer and LED](https://github.com/prabhu-omkar/cardioedge-esp32/blob/main/firmware/src/main.cpp): `firmware/src/main.cpp`

### Other components

- **ECG Front End**
- **ECG Databases**
- **Monitor User**

## Connections

- ECG Front End → ESP32 Runtime: supplies samples (evidence: `README.md`)
- Demo Clips → ESP32 Runtime: provides clips (evidence: `firmware/src/main.cpp`)
- ESP32 Runtime → ECG DSP Core: streams samples (evidence: `README.md`)
- ECG DSP Core → Signal Quality Gate: assesses quality (evidence: `firmware/lib/ecg_core/ecg_core.cpp`)
- ECG DSP Core → Beat Features: extracts beats (evidence: `README.md`)
- Signal Quality Gate → Beat Features: gates classification (evidence: `README.md`)
- ESP32 Runtime → Dual Classifiers: classifies beat (evidence: `firmware/src/main.cpp`)
- Dual Classifiers → Int8 CNN: runs CNN (evidence: `firmware/src/classifiers.cpp`)
- Dual Classifiers → Random Forest: runs forest (evidence: `firmware/src/classifiers.cpp`)
- ESP32 Runtime → Rhythm and HRV: applies rhythm logic (evidence: `README.md`)
- ESP32 Runtime → Live State: updates snapshot (evidence: `firmware/src/main.cpp`)
- ESP32 Runtime → OLED Display: refreshes display (evidence: `README.md`)
- ESP32 Runtime → Phone Dashboard: serves dashboard (evidence: `README.md`)
- Phone Dashboard → Dashboard Page: serves page (evidence: `firmware/src/webui.cpp`)
- ESP32 Runtime → Buzzer and LED: drives alarm (evidence: `README.md`)
- Monitor User → OLED Display: views verdicts (evidence: `README.md`)
- Monitor User → Phone Dashboard: views live data (evidence: `README.md`)
- ECG Databases → Patient-wise Dataset: provides records (evidence: `ml/dataset.py`)
- Patient-wise Dataset → Python DSP Binding: processes recordings (evidence: `ml/dataset.py`)
- Python DSP Binding → ECG DSP Core: calls shared DSP (evidence: `README.md`)
- Patient-wise Dataset → ML Data Utilities: writes split data (evidence: `README.md`)
- ML Data Utilities → CNN Training: loads training splits (evidence: `ml/train_cnn.py`)
- ML Data Utilities → RF Training: loads training splits (evidence: `ml/train_rf.py`)
- ML Data Utilities → Model Evaluation: loads test splits (evidence: `ml/evaluate.py`)
- CNN Training → Int8 CNN: exports device model (evidence: `ml/train_cnn.py`)
- RF Training → Random Forest: exports forest model (evidence: `README.md`)
- Model Evaluation → SQA Evaluation: measures gate effects (evidence: `ml/evaluate.py`)
- Model Evaluation → Python DSP Binding: evaluates inference (evidence: `ml/evaluate.py`)
- Capture Evaluation → Python DSP Binding: evaluates captures (evidence: `ml/eval_capture.py`)
- QRS Evaluation → Python DSP Binding: evaluates detection (evidence: `ml/eval_qrs.py`)