# jbkc/smartwatch architecture

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

- Interactive diagram: https://gitdiagram.com/jbkc/smartwatch
- Repository: https://github.com/jbkc/smartwatch

## Overview

##### Main Components
- Data Collection & Raw Data Source (Smartwatch): Although not explicitly shown as a separate module, the README indicates the smartwatch provides the raw heart rate data.
- Preprocessing Module:
– “gather_raw_data.py” suggests acquisition of unprocessed data.
– “analyse_database.py” indicates subsequent database analysis.
– “peak_detection_qrs.py” is used for QRS complex peak detection (a key step when processing heart rate signals).
- Training Module: Split into two sub-components—
– Activity Model: It likely processes and classifies activity data, with a separate wandb_logger (in training/activity_model) to record experiments.
– Heart Rate Model: Contains scripts like “hr_model.py”, “hr_model_run.py” to define and run the heart rate prediction model, and uses a moving average filter (ma_filter.py, ma_filter_run.py) to smooth signal data; this sub-component also includes its wandb_logger integration.
- Experiment Tracking/Logging: Weights & Biases (wandb) integrations present in both training subdirectories indicate external service dependency for experiment monitoring.

##### Relationships and Interactions
- Within Preprocessing, raw data is cleaned, stored, and processed (e.g., peak detection) before being forwarded to the training phase.
- After preprocessing, the processed data feeds into two training pipelines:
– The Activity Model: Trained using specific experimental setups and tracked via its dedicated wandb_logger.
– The Heart Rate Model: Involves additional steps like moving average filtering before training. Its run scripts (hr_model_run.py, ma_filter_run.py) indicate the orchestration of sequential operations.

##### Architectural Patterns and Design Principles
- Modularity: The directory structure clearly indicates separation of concerns – one for preprocessing, another for training with further division by model type.
- Pipeline Architecture: The data flows through a defined sequence—data gathering → preprocessing (signal analysis and filtering) → training models; representing a classic ETL (Extract, Transform, Load) or ML pipeline pattern.
- Extensibility: With separate modules for each training model and external logging components, the design is open to further extensions (e.g., additional models or sensors).

##### Relevant Technologies, Frameworks, and Libraries
- Python scripts for signal processing and machine learning.
- Weights & Biases (WANDB) for experiment tracking.
- Although not detailed in the file tree, consider that frameworks for data processing (e.g., NumPy, SciPy) or modeling (e.g., TensorFlow, PyTorch) might be used in the model scripts; include notes of their possible involvement if known.

##### Detail and Clarity
- Be very detailed—capture each module and sub-step represented in the file tree.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Components
    A("Smartwatch / Data Source"):::external

    %% Preprocessing Pipeline
    subgraph "Preprocessing Pipeline"
        P1("Gather Raw Data"):::preproc
        P2("Database Analysis"):::preproc
        P3("QRS Peak Detection"):::preproc
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        %% Activity Model Subgraph
        subgraph "Activity Model"
            AM("Activity Model & Logging"):::training
        end
        %% Heart Rate Model Subgraph
        subgraph "Heart Rate Model"
            HR1("HR Model Definition"):::training
            HR2("HR Model Run"):::training
            MA1("MA Filter Definition"):::training
            MA2("MA Filter Run"):::training
            HRL("HR Model Logging"):::training
            HR1 -->|"executes"| HR2
            HR2 -->|"applies"| MA1
            MA1 -->|"runs"| MA2
            MA2 -->|"logs"| HRL
        end
    end

    %% External Logging Service
    W("Weights & Biases"):::external

    %% Data Flow Connections
    A -->|"sends_data"| P1
    P1 -->|"processes"| P2
    P2 -->|"processes"| P3
    P3 -->|"feeds"| AM
    P3 -->|"feeds"| HR1
    AM -->|"tracks"| W
    HRL -->|"tracks"| W

    %% Click Events
    click A "https://github.com/jbkc/smartwatch/blob/master/README.md"
    click P1 "https://github.com/jbkc/smartwatch/blob/master/preprocessing/gather_raw_data.py"
    click P2 "https://github.com/jbkc/smartwatch/blob/master/preprocessing/analyse_database.py"
    click P3 "https://github.com/jbkc/smartwatch/blob/master/preprocessing/peak_detection_qrs.py"
    click AM "https://github.com/jbkc/smartwatch/blob/master/training/activity_model/wandb_logger.py"
    click HR1 "https://github.com/jbkc/smartwatch/blob/master/training/heartrate_model/hr_model.py"
    click HR2 "https://github.com/jbkc/smartwatch/blob/master/training/heartrate_model/hr_model_run.py"
    click MA1 "https://github.com/jbkc/smartwatch/blob/master/training/heartrate_model/ma_filter.py"
    click MA2 "https://github.com/jbkc/smartwatch/blob/master/training/heartrate_model/ma_filter_run.py"
    click HRL "https://github.com/jbkc/smartwatch/blob/master/training/heartrate_model/wandb_logger.py"

    %% Styles
    classDef external fill:#FFDAB9,stroke:#FF8C00,stroke-width:2px;
    classDef preproc fill:#ADD8E6,stroke:#0000FF,stroke-width:2px;
    classDef training fill:#90EE90,stroke:#006400,stroke-width:2px;
```
