# mikaib/hwtheremin architecture

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

- Interactive diagram: https://gitdiagram.com/mikaib/hwtheremin
- Repository: https://github.com/mikaib/hwtheremin

## Overview

##### Project type and purpose
- From the file tree and the project name “hwtheremin,” we see this is an embedded-firmware project (PlatformIO), targeting a microcontroller that implements a theremin-like instrument.
- Key clues: platformio.ini for build/deploy, src/main.c as firmware entry point, lib folders for hardware drivers (I²C/TWI and HD44780 LCD via PCF8574), and include/ for headers.

##### File structure
- Top-level:
- / – public headers (API definitions, configuration)
- lib/ – bundled driver libraries
· lib/twi – I²C (TWI) abstraction
· lib/hd44780pcf8574 – LCD driver over PCF8574 I/O expander
- src/ – application code (main.c)
- test/ – unit or integration tests
- platformio.ini – build environments, upload settings
- This separation follows a layered architecture: hardware-abstraction (lib/) → application logic (src/) → configuration (include/).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build and Deployment Layer
    subgraph "Build & Deployment"
        PIO["PlatformIO\n(platformio.ini)"]:::build
        Toolchain["GCC/ARM Toolchain"]:::build
    end

    %% Firmware Application Layer
    subgraph "Firmware Application"
        App["main.c\n(Application)"]:::app
        subgraph "Drivers"
            TWI["TWI Driver\ntwi.c / twi.h"]:::driver
            LCDDrv["HD44780 PCF8574 Driver\nhd44780pcf8574.c / hd44780pcf8574.h"]:::driver
        end
        subgraph "Public API"
            Headers["Public Headers\n(include/)"]:::api
        end
    end

    %% Test Harness
    Test["Test Harness\ntest/"]:::test

    %% Hardware Layer
    subgraph "Hardware Components"
        Sensor["ADC Sensors\n(Pitch & Volume)"]:::hardware
        MCU["Microcontroller Unit"]:::hardware
        PWM["PWM Audio Out\n(Speaker)"]:::hardware
        I2C["I2C Bus (TWI)"]:::hardware
        PCF["PCF8574 I/O Expander"]:::hardware
        LCD["HD44780 LCD"]:::hardware
    end

    %% Connections
    PIO -->|build| Toolchain
    Toolchain -->|flash| MCU
    Test -->|run tests| PIO

    App -->|includes| Headers
    App -->|calls| TWI
    App -->|calls| LCDDrv
    App -->|runs on| MCU

    Sensor -->|analog in| MCU
    MCU -->|PWM out| PWM

    MCU -->|uses TWI| TWI
    TWI -->|I2C bus| I2C
    I2C -->|wired to| PCF
    PCF -->|drives| LCD

    %% Click Events
    click App "https://github.com/mikaib/hwtheremin/blob/main/src/main.c"
    click TWI "https://github.com/mikaib/hwtheremin/blob/main/lib/twi/twi.c"
    click TWI "https://github.com/mikaib/hwtheremin/blob/main/lib/twi/twi.h"
    click LCDDrv "https://github.com/mikaib/hwtheremin/blob/main/lib/hd44780pcf8574/hd44780pcf8574.c"
    click LCDDrv "https://github.com/mikaib/hwtheremin/blob/main/lib/hd44780pcf8574/hd44780pcf8574.h"
    click Headers "https://github.com/mikaib/hwtheremin/tree/main/include/"
    click PIO "https://github.com/mikaib/hwtheremin/blob/main/platformio.ini"
    click Test "https://github.com/mikaib/hwtheremin/tree/main/test/"

    %% Styles
    classDef hardware fill:#FFD700,stroke:#333,stroke-width:1px
    classDef driver fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef app fill:#FFB6C1,stroke:#333,stroke-width:1px
    classDef api fill:#E6E6FA,stroke:#333,stroke-width:1px
    classDef build fill:#98FB98,stroke:#333,stroke-width:1px
    classDef test fill:#FFA07A,stroke:#333,stroke-width:1px
```
