# kholay47/ecg-heartbeat-classification architecture

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

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

## Overview

##### Project Type & Purpose
- This is a small full-stack web application whose backend is a Flask server (app.py) serving a machine-learning model (RandomForestClassifier) to classify ECG signals as Normal or Abnormal. The frontend is a single HTML template (index.html).

##### File Structure Analysis
- Top-level:
- app.py           → Flask application, request handlers
- ecg.ipynb        → Jupyter notebook used offline to train and evaluate the model
- model.pkl        → (implied by README) persisted RandomForestClassifier
- scaler.pkl       → (implied by README) persisted StandardScaler
- templates/       → directory for Flask’s HTML templates
└ index.html     → form for uploading ECG CSV, plus result display
- README.md, LICENSE

##### Main Components
a. User Interface (Browser)
- index.html served by Flask – upload form & result page
b. Flask Backend (app.py)
- HTTP GET “/” → render index.html
- HTTP POST “/classify” → accept uploaded CSV
c. Preprocessing Module
- pandas reads CSV → DataFrame
- StandardScaler (scaler.pkl) transforms features
d. Prediction Module
- RandomForestClassifier (model.pkl) predicts labels
e. Result Aggregator
- Count & percentage calculator
- Passes data back into template context
f. Offline Training Pipeline (ecg.ipynb)
- Data loading (PTB-XL CSV) → train/test split
- StandardScaler + RandomForestClassifier → model.pkl & scaler.pkl
g. External Libraries & Dependencies
- flask, pandas, scikit-learn, joblib

##### Component Relationships & Data Flow
- Browser → HTTP POST CSV → Flask →
→ pandas loads into DataFrame → scaler.transform → model.predict → aggregator →
→ Flask renders index.html with results → Browser
- On startup, Flask loads model.pkl & scaler.pkl into memory
- Offline: ecg.ipynb writes model.pkl & scaler.pkl (not part of runtime)

##### Architectural Patterns & Principles
- Separation of Concerns:
- Presentation Layer (templates)
- Application Layer (Flask request handlers)
- Business Logic Layer (preprocessing + prediction)
- Stateless request-response: no session management or persistent DB
- Artifact Reuse: model and scaler loaded once at startup

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        Browser["User Interface<br/>(Browser)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        FlaskApp["Flask App<br/>(app.py)"]:::backend
        Preprocessor["Preprocessor<br/>(CSV→DataFrame & scaling)"]:::backend
        Aggregator["Result Aggregator"]:::backend
    end

    %% ML Pipeline
    subgraph "ML Pipeline"
        Model["Prediction Module<br/>(RandomForestClassifier)"]:::ml
    end

    %% Artifacts
    subgraph "Persisted Artifacts"
        ModelPkl["model.pkl"]:::external
        ScalerPkl["scaler.pkl"]:::external
    end

    %% Offline Training
    OfflineNotebook["Offline Training Pipeline<br/>(ecg.ipynb)"]:::ml

    %% External Dependencies
    ExternalLibs["External Libraries<br/>(flask, pandas,<br/>scikit-learn, joblib)"]:::external

    %% Data Flow
    Browser -->|"HTTP GET \"/\""| FlaskApp
    FlaskApp -->|"serves index.html"| Browser
    Browser -->|"HTTP POST CSV"| FlaskApp
    FlaskApp -->|"reads CSV as DataFrame"| Preprocessor
    Preprocessor -->|"scaled features"| Model
    Model -->|"prediction results"| Aggregator
    Aggregator -->|"result context"| FlaskApp
    FlaskApp -->|"renders index.html with results"| Browser

    %% Startup Loading
    FlaskApp -->|"loads model.pkl & scaler.pkl"| ModelPkl
    FlaskApp --> ModelPkl
    FlaskApp --> ScalerPkl

    %% Offline process
    OfflineNotebook -->|"writes artifacts"| ModelPkl
    OfflineNotebook --> ScalerPkl

    %% External libs dependency
    FlaskApp --> ExternalLibs
    Preprocessor --> ExternalLibs
    Model --> ExternalLibs

    %% Click events
    click Browser "https://github.com/kholay47/ecg-heartbeat-classification/blob/main/templates/index.html"
    click FlaskApp "https://github.com/kholay47/ecg-heartbeat-classification/blob/main/app.py"
    click Preprocessor "https://github.com/kholay47/ecg-heartbeat-classification/blob/main/app.py"
    click Model "https://github.com/kholay47/ecg-heartbeat-classification/blob/main/app.py"
    click Aggregator "https://github.com/kholay47/ecg-heartbeat-classification/blob/main/app.py"
    click OfflineNotebook "https://github.com/kholay47/ecg-heartbeat-classification/blob/main/ecg.ipynb"
    click ModelPkl "https://github.com/kholay47/ecg-heartbeat-classification/blob/main/model.pkl"
    click ScalerPkl "https://github.com/kholay47/ecg-heartbeat-classification/blob/main/scaler.pkl"
    click ExternalLibs "https://github.com/kholay47/ecg-heartbeat-classification/blob/main/README.md"
    click ExternalLibs "https://github.com/kholay47/ecg-heartbeat-classification/blob/main/LICENSE.md"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1F618D,color:#1F618D
    classDef backend fill:#ABEBC6,stroke:#196F3D,color:#196F3D
    classDef ml fill:#F9E79F,stroke:#B7950B,color:#B7950B
    classDef external fill:#D5D8DC,stroke:#424949,color:#424949
```
