# aura-healthcare/hrv-analysis architecture

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

- Interactive diagram: https://gitdiagram.com/aura-healthcare/hrv-analysis
- Repository: https://github.com/aura-healthcare/hrv-analysis

## Overview

##### Project Type and Purpose
- It is a **pure Python library** (not a web service or microservice) that provides:
- Preprocessing of RR-intervals (outlier/ectopic-beat filtering)
- Feature extraction (time, geometrical, frequency, nonlinear)
- Plotting utilities (PSD, Poincaré, etc.)
- It is published on PyPI, has automated testing/docs pipelines, and uses Sphinx for documentation.

##### File Structure
- Top-level code:
- **hrvanalysis/** : core Python package (extract_features.py, preprocessing.py, plot.py)
- **tests/** : unit tests validating each module
- **figures/** : input images for docs
- **pyproject.toml** : build/config file
- Documentation:
- **docs/** : generated Sphinx HTML output (GitHub Pages)
- **sphinx-docs/** : source reST/Markdown for building docs
- CI & Publishing:
- **.github/workflows/** :
– ci.yml → run tests, coverage, build & deploy docs
– publish.yml → build & publish to PyPI

##### Extract Architectural Insights from README
- Core “pip install hrv-analysis” workflow
- Dependencies on SciPy, NumPy, AstroPy, Nolds, Future
- Four feature domains and several plotting methods
- A reference “architecture.png” shows three blocks: preprocess → features → plots

##### Main Components & Their Interactions
a. **User / Client**
- Imports `hrvanalysis` functions in their Python code or REPL
b. **hrvanalysis Python Package**
– **Preprocessing Module**:
- remove_outliers, remove_ectopic_beats, interpolate_nan_values
– **Feature Extraction Module**:
- get_time_domain_features, get_geometrical_features, get_frequency_domain_features, get_sampen, etc.
– **Plotting Module**:
- plot_timeseries, plot_distrib, plot_psd, plot_poincare
c. **External Dependencies**
- NumPy, SciPy, AstroPy, Nolds, Future (runtime libraries)
d. **Testing Suite**
- tests/ → invoked by CI to validate each module’s behavior
e. **Documentation Generator**
- Sphinx source (sphinx-docs/) → HTML (docs/) → published to GitHub Pages
f. **CI/CD Pipelines**
– GitHub Actions:
- CI pipeline: checkout → install deps → run tests → coverage → build docs → deploy docs
- Publish pipeline: on tag → build package → upload to PyPI

##### Architectural Patterns & Design Principles
- **Modular Separation of Concerns**:
- Preprocessing, Feature Extraction, Plotting are independent subpackages
- **Layered Data Flow**:
1) Raw RR intervals → 2) Cleaned NN intervals → 3) Feature arrays/dicts → 4) Visualizations
- **Automated Documentation + Testing**:
- CI enforces quality and auto-publishes both docs and code

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User["User / Client"]:::actor

    %% Core Python Package
    subgraph "hrvanalysis (Python Package)"
        direction TB
        Preprocessing["Preprocessing Module\nremove_outliers(), remove_ectopic_beats(), interpolate_nan_values()"]:::core
        FeatureExtraction["Feature Extraction Module\nget_time_domain_features(), get_geometrical_features(), get_frequency_domain_features(), get_sampen()"]:::core
        Plotting["Plotting Module\nplot_timeseries(), plot_distrib(), plot_psd(), plot_poincare()"]:::core
    end

    %% External Dependencies
    subgraph "Runtime Dependencies"
        direction TB
        NumPy["NumPy"]:::external
        SciPy["SciPy"]:::external
        AstroPy["AstroPy"]:::external
        Nolds["Nolds"]:::external
        Future["Future"]:::external
    end

    %% Testing Suite
    Tests["tests/ (Unit Testing Suite)"]:::tests

    %% Documentation Pipeline
    subgraph "Documentation Pipeline"
        direction TB
        SphinxSrc["sphinx-docs/source/"]:::docs
        SphinxBuild["[Sphinx Builder]"]:::docs
        GeneratedDocs["docs/ (GitHub Pages)"]:::docs
    end

    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines"
        direction TB
        CI["CI Workflow\n.github/workflows/ci.yml"]:::ci
        Publish["Publish Workflow\n.github/workflows/publish.yml"]:::ci
    end

    %% Packaging & Config
    Config["pyproject.toml\nMANIFEST.in"]:::config
    AuxFiles["README.md\nCONTRIBUTING.md\ncode-of-conduct.md\nLICENSE"]:::config
    Figures["figures/"]:::config

    %% Connections
    User -->|imports API| Preprocessing
    User --> FeatureExtraction
    User --> Plotting

    Preprocessing -->|uses| NumPy
    Preprocessing -->|uses| SciPy
    FeatureExtraction -->|uses| NumPy
    FeatureExtraction -->|uses| SciPy
    FeatureExtraction -->|uses| Nolds
    FeatureExtraction -->|uses| Future
    Plotting -->|uses| SciPy
    Plotting -->|uses| AstroPy

    Tests -->|tests| Preprocessing
    Tests --> FeatureExtraction
    Tests --> Plotting
    CI -->|runs| Tests
    CI -->|builds docs| SphinxSrc
    CI -->|deploys| GeneratedDocs
    Publish -->|builds package| Config
    Publish -->|publishes to PyPI| Config

    SphinxSrc -->|built by| SphinxBuild
    SphinxBuild -->|outputs| GeneratedDocs

    Config -->|defines build| Preprocessing
    Config --> FeatureExtraction
    Config --> Plotting

    AuxFiles -->|documentation| SphinxSrc
    Figures -->|assets| GeneratedDocs

    %% Click Events
    click Preprocessing "https://github.com/aura-healthcare/hrv-analysis/blob/master/hrvanalysis/preprocessing.py"
    click FeatureExtraction "https://github.com/aura-healthcare/hrv-analysis/blob/master/hrvanalysis/extract_features.py"
    click Plotting "https://github.com/aura-healthcare/hrv-analysis/blob/master/hrvanalysis/plot.py"
    click User "https://github.com/aura-healthcare/hrv-analysis/blob/master/README.md"
    click Tests "https://github.com/aura-healthcare/hrv-analysis/tree/master/tests/"
    click CI "https://github.com/aura-healthcare/hrv-analysis/blob/master/.github/workflows/ci.yml"
    click Publish "https://github.com/aura-healthcare/hrv-analysis/blob/master/.github/workflows/publish.yml"
    click SphinxSrc "https://github.com/aura-healthcare/hrv-analysis/tree/master/sphinx-docs/source/"
    click GeneratedDocs "https://github.com/aura-healthcare/hrv-analysis/tree/master/docs/"
    click Config "https://github.com/aura-healthcare/hrv-analysis/blob/master/pyproject.toml"
    click Figures "https://github.com/aura-healthcare/hrv-analysis/tree/master/figures/"

    %% Styles
    classDef actor fill:#f9f,stroke:#333,stroke-width:1px
    classDef core fill:#bbdefb,stroke:#1e88e5,stroke-width:1px
    classDef external fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px
    classDef tests fill:#eeeeee,stroke:#616161,stroke-dasharray: 5 5
    classDef docs fill:#eceff1,stroke:#546e7a,stroke-width:1px
    classDef ci fill:#ffe0b2,stroke:#ef6c00,stroke-width:1px
    classDef config fill:#f3e5f5,stroke:#8e24aa,stroke-width:1px
```
