# tttapa/control-surface architecture

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

- Interactive diagram: https://gitdiagram.com/tttapa/control-surface
- Repository: https://github.com/tttapa/control-surface

## Overview

##### Project Type and Purpose
- This is a C++ library (with accompanying examples, tests, documentation, and build scripts) designed for Arduino-compatible boards. Its purpose is to provide a flexible abstraction layer for MIDI communications and to support various input/output control elements (potentiometers, buttons, LEDs, rotary encoders, displays, etc.) for building custom MIDI controllers.
- The README clearly explains that it supports different MIDI interfaces (USB, 5‑pin DIN serial, BLE, WiFi AppleMIDI, etc.) and a range of MIDI control elements, along with additional hardware abstraction for multiplexers, shift registers, and even audio support on boards like Teensy.

##### Analyzing the File Structure
- Top-Level Organization:
– Directories such as “src”, “doxygen”, “examples” and “test” indicate separate zones for the core library (source code), documentation and build configurations, demonstration sketches, and automated tests.
- Within “src” you find multiple subdirectories (AH, Audio, Banks, Control_Surface, Def, Display, MIDI_Constants, MIDI_Inputs, MIDI_Interfaces, MIDI_Outputs, MIDI_Parsers, MIDI_Senders, Selectors, Settings, Submodules, etc.) that give clear hints about a modular architecture.
- The “src/AH” subfolder contains many of the low-level abstractions (containers, debugging utilities, hardware helpers, digital filters, math routines, and STL fallbacks) that underpin the library.
- MIDI-related functionalities are spread across directories such as “MIDI_Constants”, “MIDI_Inputs”, “MIDI_Interfaces”, “MIDI_Outputs”, “MIDI_Parsers” and “MIDI_Senders”. This separation reflects a layered design where MIDI message handling and the actual physical interfaces are decoupled.
- The presence of “CMakeLists.txt”, “CMakePresets.json”, and directories for CI workflows indicates that the build, documentation generation (using Doxygen), and continuous integration are integral parts of the project.

##### Key Components and Interactions
a. Core Library Modules:
– The “Control_Surface” module (in src/Control_Surface and related parts) is the main entry point that integrates the various controls.
– “AH” (Arduino Helpers) provides the hardware abstraction and utility functions needed by many elements.
b. MIDI Abstraction Layer:
– The library implements a flexible MIDI abstraction layer with multiple interface implementations. The “MIDI_Interfaces” directory holds concrete classes that implement MIDI over USB, BLE (BluetoothMIDI_Interface), Serial (5‑pin DIN) and even AppleMIDI.
c. Control Elements:
– MIDI Output Elements (found in “MIDI_Outputs”, “Banks”, “Selectors”) are responsible for sending MIDI messages (e.g., control change messages, note on/off) from hardware controls.
– MIDI Input Elements (in “MIDI_Inputs” and “Display”) process incoming messages to drive feedback components like LEDs, VU meters, OLED displays, and seven-segment displays.
d. Auxiliary Modules:
– “MIDI_Constants” defines the common definitions and enumerations used across the code.
– “MIDI_Parsers” and “MIDI_Senders” are responsible for parsing incoming data streams and for creating outgoing messages.
– “Settings” and “Def” contain configuration, type definitions, and default parameters.
– “Audio” support (only in some boards) extends the abstraction to the audio domain.
e. Build, Test, Documentation, and Examples:
– Doxygen files and scripts generate the project documentation.
– The “examples” and “test” directories offer usage samples and automated tests that exercise various features.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Abstraction Layer
    subgraph "Hardware Abstraction Layer"
        AH["AH Hardware Abstraction"]:::hardware
    end

    %% Configuration and Definitions
    subgraph "Configuration"
        Def["Definitions"]:::config
        Set["Settings"]:::config
    end

    %% Core Engine
    subgraph "Core Engine"
        CSE["Control Surface Engine"]:::core
        Audio["Audio Support"]:::aux
        CustomElem["Custom Element Extension"]:::core
    end

    %% MIDI Abstraction Layer
    subgraph "MIDI Abstraction Layer"
        MIDIInt["MIDI Interfaces"]:::midi
        MIDIOut["MIDI Output Elements"]:::midi
        MIDIIn["MIDI Input Elements"]:::midi
        MIDIPar["MIDI Parsers"]:::midi
        MIDISend["MIDI Senders"]:::midi
        MIDIConst["MIDI Constants"]:::midi
    end

    %% Ecosystem
    subgraph "Ecosystem"
        Doc["Documentation"]:::external
        Ex["Examples"]:::external
        Test["Tests"]:::external
        ExtMIDI["External MIDI Devices"]:::external
    end

    %% Connections
    AH --> CSE
    Def --> CSE
    Set --> CSE
    Audio --> CSE
    CSE -->|"sends_MIDI"| MIDIOut
    CSE -->|"routes_MIDI"| MIDIInt
    CSE -->|"allows_extension"| CustomElem
    MIDIInt -->|"feedback"| MIDIIn
    MIDIInt -->|"invokes_parser"| MIDIPar
    MIDIInt -->|"invokes_sender"| MIDISend
    MIDIConst -->|"defines"| MIDIPar
    MIDIConst -->|"defines"| MIDISend
    MIDIInt -->|"outputs_to"| ExtMIDI
    Doc -.-> CSE
    Ex -.-> CSE
    Test -.-> CSE

    %% Click Events
    click AH "https://github.com/tttapa/control-surface/tree/main/src/AH"
    click CSE "https://github.com/tttapa/control-surface/tree/main/src/Control_Surface"
    click MIDIInt "https://github.com/tttapa/control-surface/tree/main/src/MIDI_Interfaces"
    click MIDIIn "https://github.com/tttapa/control-surface/tree/main/src/MIDI_Inputs"
    click MIDIOut "https://github.com/tttapa/control-surface/tree/main/src/MIDI_Outputs"
    click MIDIConst "https://github.com/tttapa/control-surface/tree/main/src/MIDI_Constants"
    click MIDIPar "https://github.com/tttapa/control-surface/tree/main/src/MIDI_Parsers"
    click MIDISend "https://github.com/tttapa/control-surface/tree/main/src/MIDI_Senders"
    click Def "https://github.com/tttapa/control-surface/tree/main/src/Def"
    click Set "https://github.com/tttapa/control-surface/tree/main/src/Settings"
    click Audio "https://github.com/tttapa/control-surface/tree/main/src/Audio"
    click Doc "https://github.com/tttapa/control-surface/tree/main/doxygen"
    click Ex "https://github.com/tttapa/control-surface/tree/main/examples"
    click Test "https://github.com/tttapa/control-surface/tree/main/test"

    %% Styling
    classDef hardware fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef config fill:#ffe680,stroke:#333,stroke-width:2px;
    classDef core fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef midi fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef aux fill:#f0d6f8,stroke:#333,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#333,stroke-width:2px;
```
