How robertbendun/harmonia works
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.