# jerry20091103/vibration-tuner architecture

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

- Interactive diagram: https://gitdiagram.com/jerry20091103/vibration-tuner
- Repository: https://github.com/jerry20091103/vibration-tuner

## Overview

##### Project Type and Purpose
- This is an embedded-firmware project targeting an Arduino-compatible microcontroller (managed via PlatformIO/VSCode).
- It implements three core user-facing features—Metronome, Prompter, and Tuner—each with its own UI “Page.”
- It uses real-time signal processing (Butterworth filter, controls) and a hardware abstraction layer to drive on-device peripherals (display, audio, buttons).

##### File Structure
- Top-level:
- code/ – the main firmware project managed by PlatformIO.
- local_test/ – PC‐based LVGL port for local UI development.
- teleprompter.py – host‐side script (likely for generating or uploading prompts).
- Inside code/:
- conf/ – LVGL configuration headers.
- / – public headers: pages (MetronomePage.h, TunerPage.h, etc.), hardware abstraction, filters, GUI utilities, controls.
- src/ – implementation files mirroring include/, plus main.cpp as the entry point.
- lib/, test/ – third-party libraries and unit tests.
- platformio.ini – build configuration.

##### README.md
- Confirms PlatformIO + Arduino framework.
- Naming conventions and setup steps—no direct architectural guidance.

##### Main Components & Their Interactions
a. Hardware Platform (bottom layer)
- MCU (Arduino) – CPU running firmware.
- Peripherals: display (LVGL), speaker/buzzer, sensor(s) for tuner, buttons/encoder.
b. Hardware Abstraction Layer (HAL)
- code/include/hardware.h + hardware.cpp
- guiUtility, controls – wrappers around LVGL and input devices.
c. Real-Time Signal Processing
- butterworth filter, realtime_filter, controls – DSP routines to filter input for tuner.
d. Application Modules (“Pages”)
- MetronomePage, TunerPage, PrompterPage – each encapsulates:
– OptionsPage (UI controls)
– Core logic (Metronome.cpp, Tuner.cpp, Prompter.cpp)
e. System Orchestrator
- main.cpp – initializes LVGL, HAL, modules, and dispatches events / updates pages in the main loop.
f. Build, Test & Host Integration
- PlatformIO build (VSCode) → firmware binary → flash to device.
- local_test for PC-side LVGL dev.
- teleprompter.py for host-to-device communication or prompt file prep.

##### Architectural Patterns & Design Principles
- Layered architecture: Hardware → HAL → DSP → Application.
- Modular UI pages: clear separation of feature logic vs. options vs. rendering.
- Dependency injection via “include” interfaces.
- Test harness under code/test for unit tests.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host & Tools Layer
    subgraph "Host & Tools" 
        direction TB
        Teleprompter["teleprompter.py"]:::host
        LocalTest["local_test/lv_port_pc_vscode"]:::host
    end

    %% Build & Test Layer
    subgraph "Build & Test"
        direction TB
        PlatformIO["platformio.ini"]:::host
        UnitTests["code/test/test_main.cpp"]:::host
        TestReadme["code/test/README"]:::host
    end

    %% Application Layer
    subgraph "Application Modules" 
        direction TB
        subgraph "Metronome Module"
            direction TB
            MetLogic["Metronome"]:::app
            MetPage["MetronomePage"]:::app
            MetOpts["MetronomeOptionsPage"]:::app
        end
        subgraph "Tuner Module"
            direction TB
            TunLogic["Tuner"]:::app
            TunPage["TunerPage"]:::app
        end
        subgraph "Prompter Module"
            direction TB
            ProLogic["Prompter"]:::app
            ProPage["PrompterPage"]:::app
            ProOpts["PrompterOptionsPage"]:::app
        end
        PagesUtil["pages (registry/helpers)"]:::app
    end

    %% DSP Layer
    subgraph "Signal Processing" 
        direction TB
        Butter["Butterworth Filter"]:::dsp
        RealtimeF["Realtime Filter"]:::dsp
    end

    %% HAL & System Services Layer
    subgraph "Hardware Abstraction Layer & Services"
        direction TB
        HALHeader["hardware.h"]:::firmware
        HALImpl["hardware.cpp"]:::firmware
        GUIUtilH["guiUtility.h"]:::firmware
        GUIUtilC["guiUtility.cpp"]:::firmware
        ControlsH["controls.h"]:::firmware
        ControlsC["controls.cpp"]:::firmware
    end

    %% Orchestrator
    Main["main.cpp"]:::firmware

    %% Hardware Layer
    subgraph "Hardware Platform"
        direction TB
        MCU["MCU (Arduino)"]:::hardware
        Display["Display (LVGL)"]:::hardware
        Speaker["Speaker/Buzzer"]:::hardware
        Sensor["Sensor (Mic)"]:::hardware
        Buttons["Buttons/Encoder"]:::hardware
    end

    %% Connections
    Teleprompter -->|"Prepare prompts"| Main
    LocalTest -->|"UI dev port"| Main
    PlatformIO -->|"Build firmware"| Main
    UnitTests -->|"Test harness"| PagesUtil
    TestReadme -->|"Docs"| UnitTests

    Main -->|"init HAL & LVGL"| HALHeader
    Main -->|"call pages registry"| PagesUtil
    Main -->|"dispatch updates"| MetLogic
    Main -->|"dispatch updates"| TunLogic
    Main -->|"dispatch updates"| ProLogic

    MetLogic -->|"render UI"| MetPage
    MetLogic -->|"options"| MetOpts
    TunLogic -->|"render UI"| TunPage
    ProLogic -->|"render UI"| ProPage
    ProLogic -->|"options"| ProOpts

    MetPage -->|"uses GUI utils"| GUIUtilC
    TunPage -->|"uses GUI utils"| GUIUtilC
    ProPage -->|"uses GUI utils"| GUIUtilC

    GUIUtilC -->|"HW wrapper"| HALImpl
    ControlsC -->|"HW wrapper"| HALImpl

    HALImpl -->|"reads"| Sensor
    HALImpl -->|"reads"| Buttons
    HALImpl -->|"writes"| Display
    HALImpl -->|"writes"| Speaker

    Sensor -->|"signal in"| Butter
    Butter -->|"filtered"| RealtimeF
    RealtimeF -->|"tone analysis"| TunLogic

    classDef hardware fill:#dddddd,stroke:#333;
    classDef firmware fill:#bbddff,stroke:#333;
    classDef dsp fill:#aaccff,stroke:#333;
    classDef app fill:#88bbff,stroke:#333;
    classDef host fill:#ccffcc,stroke:#333;

    %% Click Events
    click HALHeader "https://github.com/jerry20091103/vibration-tuner/blob/main/code/include/hardware.h"
    click HALImpl "https://github.com/jerry20091103/vibration-tuner/blob/main/code/src/hardware.cpp"
    click GUIUtilH "https://github.com/jerry20091103/vibration-tuner/blob/main/code/include/guiUtility.h"
    click GUIUtilC "https://github.com/jerry20091103/vibration-tuner/blob/main/code/src/guiUtility.cpp"
    click ControlsH "https://github.com/jerry20091103/vibration-tuner/blob/main/code/include/controls.h"
    click ControlsC "https://github.com/jerry20091103/vibration-tuner/blob/main/code/src/controls.cpp"
    click Butter "https://github.com/jerry20091103/vibration-tuner/blob/main/code/include/butterworth.h"
    click Butter "https://github.com/jerry20091103/vibration-tuner/blob/main/code/src/butterworth.cpp"
    click RealtimeF "https://github.com/jerry20091103/vibration-tuner/blob/main/code/include/realtime_filter.h"
    click MetLogic "https://github.com/jerry20091103/vibration-tuner/blob/main/code/include/Metronome.h"
    click MetLogic "https://github.com/jerry20091103/vibration-tuner/blob/main/code/src/Metronome.cpp"
    click MetPage "https://github.com/jerry20091103/vibration-tuner/blob/main/code/include/MetronomePage.h"
    click MetPage "https://github.com/jerry20091103/vibration-tuner/blob/main/code/src/MetronomePage.cpp"
    click MetOpts "https://github.com/jerry20091103/vibration-tuner/blob/main/code/include/MetronomeOptionsPage.h"
    click MetOpts "https://github.com/jerry20091103/vibration-tuner/blob/main/code/src/MetronomeOptionsPage.cpp"
    click TunLogic "https://github.com/jerry20091103/vibration-tuner/blob/main/code/include/Tuner.h"
    click TunLogic "https://github.com/jerry20091103/vibration-tuner/blob/main/code/src/Tuner.cpp"
    click TunPage "https://github.com/jerry20091103/vibration-tuner/blob/main/code/include/TunerPage.h"
    click TunPage "https://github.com/jerry20091103/vibration-tuner/blob/main/code/src/TunerPage.cpp"
    click ProLogic "https://github.com/jerry20091103/vibration-tuner/blob/main/code/include/Prompter.h"
    click ProLogic "https://github.com/jerry20091103/vibration-tuner/blob/main/code/src/Prompter.cpp"
    click ProPage "https://github.com/jerry20091103/vibration-tuner/blob/main/code/include/PrompterPage.h"
    click ProPage "https://github.com/jerry20091103/vibration-tuner/blob/main/code/src/PrompterPage.cpp"
    click ProOpts "https://github.com/jerry20091103/vibration-tuner/blob/main/code/include/PrompterOptionsPage.h"
    click ProOpts "https://github.com/jerry20091103/vibration-tuner/blob/main/code/src/PrompterOptionsPage.cpp"
    click Main "https://github.com/jerry20091103/vibration-tuner/blob/main/code/src/main.cpp"
    click PagesUtil "https://github.com/jerry20091103/vibration-tuner/blob/main/code/include/pages.h"
    click PagesUtil "https://github.com/jerry20091103/vibration-tuner/blob/main/code/src/pages.cpp"
    click PlatformIO "https://github.com/jerry20091103/vibration-tuner/blob/main/code/platformio.ini"
    click UnitTests "https://github.com/jerry20091103/vibration-tuner/blob/main/code/test/test_main.cpp"
    click LocalTest "https://github.com/jerry20091103/vibration-tuner/tree/main/local_test/lv_port_pc_vscode"
```
