# vinny-nguyen/theriffler architecture

> Architecture diagram of the GitHub repository vinny-nguyen/theriffler, 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/vinny-nguyen/theriffler
- Repository: https://github.com/vinny-nguyen/theriffler

## Overview

##### Main Components
- Input Data Sources: Guitar Pro (.gp5) files and corresponding guitar tabs (in the tabs directory). These are the raw musical inputs.
- Python Processing Layer:
- The parse_guitar.py script reads the .gp5 files, utilizing the pyguitarpro library, and converts them into a structured JSON format.
- The play_guitar.py script is responsible for simulating song playback and sending the generated commands in real time.
- Communication Interface: The serial interface between the Python scripts and the Arduino board. This is how the JSON commands are transmitted.
- Arduino Microcontroller Layer:
- The Arduino/Guitar_low_level sketch (Guitar_low_level.ino) reads the commands (likely via serial) and then controls the servomotors.
- Hardware – Servomotors: Represented as the final output devices (fret pressers and string pluckers) activated by the Arduino.

##### Relationships and Interactions
- The system begins by the user obtaining or placing Guitar Pro (.gp5) files in the proper location. These files or their interpreted outputs (parsed JSON) form the input dataset.
- The Python script (parse_guitar.py) processes the .gp5 files and creates JSON files (e.g., o-canada.json, god-save-the-queen.json) which contain time-stamped commands (press, unpress, fret and string numbers, durations).
- Once parsed, the play_guitar.py script takes these JSON files to simulate the song timeline. It then forwards the commands in real time via a serial connection to the Arduino.
- The Arduino listens on the serial port; based on the received instructions, it activates the servomotors to physically play the guitar.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The design distinctly separates the “data processing and simulation” (Python layer) from the “hardware actuation” (Arduino layer).
- Real-time Communication: The design includes real-time serial communication as a bridge between high-level song simulation and low-level actuator control.
- Modularity and Extensibility: With dedicated scripts for parsing and playback, the system can be extended or modified easily (e.g., supporting additional song formats or adding error-checking/feedback).

##### Relevant Technologies/Frameworks
- Python and the pyguitarpro library for parsing .gp5 files.
- The Arduino IDE with C/C++ code to program the microcontroller.
- Serial communication protocols to transmit commands from the Python environment to the Arduino hardware.

##### In Summary
- Data Input: Guitar Pro (.gp5) Files and Tabs → Python Parser (parse_guitar.py)
- Data Transformation: JSON Generation from the .gp5 files (with sample outputs like o-canada.json) → Python Playback Engine (play_guitar.py)
- Communication: Real-time Serial Interface → Arduino
- Actuation: Arduino’s control over servomotors to perform the physical actions on the guitar

## Diagram (Mermaid)

```mermaid
graph TD
    %% Input Layer
    subgraph "Input Data Sources"
        InputFiles("Guitar Pro Files & Tabs"):::input
    end

    %% Python Processing Layer
    subgraph "Python Processing Layer"
        Parser("Guitar Pro Parser (parse_guitar.py)"):::python
        JSON("JSON Data Output"):::python
        Playback("Playback Engine (play_guitar.py)"):::python
    end

    %% Communication Interface
    subgraph "Communication Interface"
        Serial("Serial Communication"):::comm
    end

    %% Arduino Microcontroller Layer
    subgraph "Arduino Microcontroller Layer"
        Arduino("Guitar Motor Controller (Guitar_low_level.ino)"):::arduino
    end

    %% Hardware Layer
    subgraph "Hardware"
        Servos("Servomotors"):::hardware
    end

    %% Data Flow
    InputFiles -->|"processes"| Parser
    Parser -->|"outputs"| JSON
    JSON -->|"consumed_by"| Playback
    Playback -->|"sends_commands"| Serial
    Serial -->|"transmits"| Arduino
    Arduino -->|"activates"| Servos

    %% Click Events
    click InputFiles "https://github.com/vinny-nguyen/theriffler/tree/main/tabs/"
    click Parser "https://github.com/vinny-nguyen/theriffler/blob/main/parse_guitar.py"
    click Playback "https://github.com/vinny-nguyen/theriffler/blob/main/play_guitar.py"
    click Arduino "https://github.com/vinny-nguyen/theriffler/blob/main/Arduino/Guitar_low_level/Guitar_low_level.ino"

    %% Styles
    classDef input fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef python fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef comm fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
    classDef arduino fill:#82E0AA,stroke:#196F3D,stroke-width:2px;
    classDef hardware fill:#F5B7B1,stroke:#943126,stroke-width:2px;
```
