# robertbendun/harmonia architecture

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

- Interactive diagram: https://gitdiagram.com/robertbendun/harmonia
- Repository: https://github.com/robertbendun/harmonia

## Overview

##### Project Type and Purpose

**Project Type:**
Harmonia is a **full-stack web application** developed in Rust, designed to interface with MIDI devices using a modified version of [Ableton/Link](https://github.com/Ableton/link). It serves as a synchronization tool tailored for laptop orchestras, enabling coordinated MIDI playback across multiple devices.

**Purpose:**
The primary goal of Harmonia is to provide a seamless interface for playing synchronized MIDI files, facilitating collaborative performances in a laptop orchestra setting. It includes functionalities such as MIDI upload/download, real-time synchronization, health checks, and state management.

##### File Structure

**Top-Level Directories and Files:**

- **`.github/`**: Contains GitHub workflow configurations for documentation, integration tests, and releases.
- **`examples/`**: Houses example projects demonstrating Lua and C integrations (`lua-shared-memory`), indicating extensibility and interoperability features.
- **`public/`**: Contains frontend assets (`index.css`, `index.js`), suggesting a web-based user interface.
- **`src/`**: Includes Rust source files responsible for various backend functionalities such as audio engine, networking, handlers, and version management.
- **`tests/`**: Comprises MIDI files for testing and an integration script (`integration.py`), highlighting a focus on thorough testing.

**Architectural Patterns and Choices:**

- **Modular Backend:** The `src/` directory is segmented into multiple Rust modules (e.g., `audio_engine.rs`, `net.rs`), indicating a modular architecture.
- **Web Interface:** Presence of `public/` with CSS and JS files suggests a clear separation between frontend and backend.
- **CI/CD Pipelines:** GitHub workflows for documentation, testing, and releases imply automated integration and deployment processes.
- **Extensibility:** The `examples/` directory with Lua and C integrations points to an extensible system that can interface with other programming languages and systems.

##### README for Additional Insights

**Architecture and Dependencies:**

- **Web Server:** Implemented in Rust, handling HTTP requests and serving the frontend.
- **MIDI Subsystem:** Integrates with a patched version of Ableton/Link for synchronization.
- **State Management:** Capabilities to save and restore server state indicate persistence mechanisms, though a specific database is not mentioned.
- **Extensibility Points:** Examples using Lua suggest scripting or plugin capabilities.
- **Technologies:** Utilizes Rust for backend robustness, Web technologies (CSS/JS) for the frontend, and C/C++ integrations for performance-critical components.

**Documentation and Developer Resources:**

- Developer documentation is available online and can be generated locally using Cargo.
- Architecture details are documented in `uam/architecture.adoc`.

**a. Identify the Main Components:**

##### Frontend
- **Web Interface:** `public/index.css`, `public/index.js`
- **User Interactions:** MIDI upload/download, playback controls, visual indicators.

##### Backend
- **Web Server:** Handles HTTP requests, serves frontend assets.
- **MIDI Engine:** Manages MIDI synchronization using Ableton/Link.
- **State Management:** Saves and restores server state.
- **API Layer:** Exposes endpoints for frontend interactions.

##### Integration Components
- **Lua/C Extensions:** `examples/lua-shared-memory/` demonstrates interoperability.
- **Patched Libraries:** Modified Ableton/Link for enhanced functionality.

##### Testing and CI/CD
- **Automated Workflows:** GitHub Actions for documentation, testing, and releases.
- **Test Suites:** MIDI files and integration scripts for validating functionality.

##### Documentation and Support
- **Developer Docs:** Accessible online and locally via Cargo.
- **Research Documentation:** `uam/` directory for R&D insights.

**b. Determine Relationships and Interactions:**

- **Frontend ↔ Backend:**
- The frontend communicates with the backend through RESTful APIs served by the Rust web server.

- **Backend ↔ MIDI Engine:**
- The backend interfaces with the MIDI engine, which utilizes the patched Ableton/Link for synchronization.

- **Backend ↔ Integration Components:**
- Lua and C extensions interact with the backend to extend functionality or interface with other systems.

- **CI/CD Pipelines ↔ All Components:**
- Automated GitHub workflows ensure continuous integration and deployment across documentation, testing, and release management.

**c. Highlight Architectural Patterns and Design Principles:**

- **Modular Architecture:** Separation of concerns across different modules (frontend, backend, integration).
- **Extensibility:** Ability to incorporate Lua/C extensions for additional functionalities.
- **Automated CI/CD:** Ensures code quality and streamlined deployments.
- **Robust State Management:** Facilitates persistence and reliability of server states.

**d. Include Relevant Technologies, Frameworks, or Libraries:**

- **Programming Languages:** Rust (backend), JavaScript/CSS (frontend), C/C++ and Lua (extensions).
- **Libraries/Frameworks:**
- **Rust Libraries:** Pertinent for web server implementation and MIDI handling.
- **Ableton/Link:** Core synchronization technology, with custom patches.
- **Tools:**
- **Cargo:** Rust’s package manager and build system.
- **GitHub Actions:** For CI/CD workflows.

##### Elements

- **Clear Labels for Each Component:**
- Frontend (Web Interface)
- Backend (Rust Web Server)
- MIDI Engine
- Ableton/Link Integration
- Lua/C Extensions
- CI/CD Pipelines

- Frontend ↔ Backend communication via APIs.
- Backend → MIDI Engine → Ableton/Link for synchronization.
- Backend ↔ Lua/C Extensions for extended functionalities.
- CI/CD Pipelines → All relevant components for automated processes.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Subgraphs

    subgraph Frontend
        WebInterface["Web Interface"]:::frontend
        indexCSS["index.css"]:::frontend
        indexJS["index.js"]:::frontend
    end

    subgraph Backend
        WebServer["Web Server"]:::backend
        APIHandlers["API Handlers"]:::backend
        MIDEngine["MIDI Engine"]:::backend
        AbletonLink["Ableton/Link"]:::backend
    end

    subgraph Integration
        LuaCExtensions["Lua/C Extensions"]:::integration
    end

    subgraph CICD
        CICD_Pipelines["CI/CD Pipelines"]:::cicd
    end

    subgraph Testing
        TestingSuites["Testing Suites"]:::testing
    end

    subgraph Documentation
        Documentation["Documentation"]:::documentation
    end

    %% Connections

    WebInterface -->|"APIs"| WebServer
    WebInterface --> indexCSS
    WebInterface --> indexJS
    WebServer --> APIHandlers
    WebServer --> MIDEngine
    MIDEngine --> AbletonLink
    WebServer --> LuaCExtensions
    CICD_Pipelines --> WebInterface
    CICD_Pipelines --> WebServer
    CICD_Pipelines --> LuaCExtensions
    CICD_Pipelines --> TestingSuites
    TestingSuites --> WebServer
    TestingSuites --> MIDEngine
    Documentation --> WebServer

    %% Click Events

    click indexCSS "https://github.com/robertbendun/harmonia/blob/main/public/index.css"
    click indexJS "https://github.com/robertbendun/harmonia/blob/main/public/index.js"
    click WebServer "https://github.com/robertbendun/harmonia/blob/main/src/harmonia.rs"
    click APIHandlers "https://github.com/robertbendun/harmonia/blob/main/src/handlers.rs"
    click MIDEngine "https://github.com/robertbendun/harmonia/blob/main/src/audio_engine.rs"
    click LuaCExtensions "https://github.com/robertbendun/harmonia/tree/main/examples/lua-shared-memory/"
    click CICD_Pipelines "https://github.com/robertbendun/harmonia/tree/main/.github/workflows/"
    click TestingSuites "https://github.com/robertbendun/harmonia/tree/main/tests/"
    click Documentation "https://github.com/robertbendun/harmonia/blob/main/uam/architecture.adoc"

    %% Styles

    classDef frontend fill:#a2c4c9,stroke:#000,stroke-width:1px
    classDef backend fill:#b6d7a8,stroke:#000,stroke-width:1px
    classDef integration fill:#f9cb9c,stroke:#000,stroke-width:1px
    classDef cicd fill:#c9daf8,stroke:#000,stroke-width:1px
    classDef testing fill:#d9d2e9,stroke:#000,stroke-width:1px
    classDef documentation fill:#e2e2e2,stroke:#000,stroke-width:1px

    %% Assign classes

    class WebInterface,indexCSS,indexJS frontend
    class WebServer,APIHandlers,MIDEngine,AbletonLink backend
    class LuaCExtensions integration
    class CICD_Pipelines cicd
    class TestingSuites testing
    class Documentation documentation
```
