# mrene/minidsp-rs architecture

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

- Interactive diagram: https://gitdiagram.com/mrene/minidsp-rs
- Repository: https://github.com/mrene/minidsp-rs

## Overview

##### Project Type and Purpose
- Project type: An open-source control tool with both a CLI (`minidsp` crate) and an optional long-running daemon exposing an HTTP API.
- Purpose: Send configuration and control commands to various MiniDSP hardware over USB/HID, TCP or WebSocket transports, and optionally host an HTTP/OpenAPI interface for integrations.

##### File Structure
- Monorepo with multiple Cargo crates:
– Root workspace (Cargo.toml) orchestrates sub-crates.
– `minidsp/` – CLI binary with local commands, config parsing, discovery and transport.
– `daemon/` – HTTP + TCP server, device management, discovery tasks.
– `protocol/` – Core packet formats, fixed-point math, device-specific codecs, commands.
– `devtools/` – Code-generation utilities run at build-time (XML→Rust specs).
– `docs/` and `README-API.md` – Documentation sources, OpenAPI spec.
- Transport variations under `minidsp/src/transport`: HID, net (TCP), WebSocket, mock.
- Configuration and packaging in Nix, Debian, Docker for RPi, CI workflows under `.github`.

##### README for Additional Insights
- CLI usage examples and HTTP API reference.
- Supported devices list corresponds 1:1 to `protocol/src/device/*` modules.

##### Main Components & Their Relationships
a. Frontend Clients:
– CLI app (`minidsp` binary).
– HTTP/OpenAPI client (e.g. browser UIs, scripts) hitting the daemon’s endpoints.
b. Daemon:
– HTTP server (OpenAPI spec, Redoc UI).
– Optional raw TCP socket interface.
– DeviceManager & Discovery subsystem (registry of attached devices, status polling).
c. Protocol Layer:
– Serialization/deserialization of commands and packets.
– Device-specific argument conversion (fixed-point, registers).
d. Transport Layer:
– HID transport to local USB devices.
– TCP/WebSocket transport to remote devices.
– Multiplexer allowing multiple clients to share a transport.
e. Hardware:
– Physical MiniDSP units (various models).
f. Build/Codegen (Static components):
– Devtools codegen (XML configs → Rust spec modules).
– Documentation generator (docs/static, docs/build.sh).

- Within “Daemon,” show sub-modules: HTTP API, TCP API, DeviceManager, Discovery.
- Within “Transport,” split into HID, Net (TCP), WS, Mock.
- “protocol” crate as a shared library used by both `minidsp` (CLI) and `daemon`.
- Separate build-time tools (Devtools, Docs pipeline) into a side group labeled “Build/Docs.”

##### Data Flows & Dependencies
- CLI → Protocol API → Transport → Hardware.
- HTTP API handlers → DeviceManager → Protocol → Transport → Hardware.
- Discovery tasks periodically scan transports → update registry.
- Devtools → (codegen) → protocol/src/device → rustc.

##### Architectural Patterns & Principles
- Modular Rust crates for separation of concerns (CLI vs. server vs. protocol vs. transport).
- Adapter pattern: transport implementations behind a common interface.
- Plugin-like device definitions in `protocol/src/device/*.rs`.
- OpenAPI-first for HTTP interface, enabling auto-generated docs.

##### Essential Details to Capture
- The dual nature (CLI vs. API) both depending on the same core libraries.
- The layered dependency: Handler → DeviceManager → Protocol → Transport.
- Discovery registry updating asynchronous tasks.
- The devtools codegen pipeline as an offline build step.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Clients
    subgraph "Frontend Clients"
        CLI["CLI (minidsp)"]:::runtime
        HTTPClient["HTTP/OpenAPI Client"]:::runtime
    end

    %% Daemon Service
    subgraph "Daemon"
        HTTPAPI["HTTP Server (daemon)"]:::runtime
        WSAPI["WebSocket Support"]:::runtime
        TCPAPI["Raw TCP Socket API"]:::runtime
        DeviceManager["DeviceManager"]:::runtime
        Discovery["Discovery Subsystem"]:::runtime
    end

    %% Core Library
    Protocol["Protocol Crate"]:::shared

    %% Transport Implementations
    subgraph "Transport Layer"
        HID["HID (USB)"]:::transport
        Net["Network (TCP)"]:::transport
        WS["WebSocket"]:::transport
        Mock["Mock (Testing)"]:::transport
    end

    %% Hardware
    Hardware["MiniDSP Hardware"]:::external

    %% Build/Docs
    subgraph "Build / Docs"
        Devtools["Devtools Codegen"]:::build
        Docs["Documentation Pipeline"]:::build
    end

    %% CI/CD Pipeline
    Pipeline["CI/CD Workflows"]:::build

    %% Connections
    CLI -->|"uses"| Protocol
    CLI -->|"optional TCP Server"| TCPAPI
    HTTPClient -->|"calls"| HTTPAPI
    HTTPAPI -->|"manages"| DeviceManager
    WSAPI -->|"upgrades"| HTTPAPI
    TCPAPI -->|"manages"| DeviceManager
    DeviceManager -->|"issues commands"| Protocol
    Discovery -->|"scans transports"| Protocol
    Protocol -->|"sends packets via"| HID
    Protocol -->|"sends packets via"| Net
    Protocol -->|"sends packets via"| WS
    Protocol -->|"mock commands"| Mock
    HID -->|"> USB"| Hardware
    Net -->|"> TCP"| Hardware
    WS -->|"> WS"| Hardware
    Discovery -->|"updates"| DeviceManager

    Devtools -->|"generates code into"| Protocol
    Docs -->|"builds specs & UI"| HTTPAPI
    Pipeline -->|"builds/packages"| CLI
    Pipeline -->|"builds/packages"| HTTPAPI

    %% Click Events
    click CLI "https://github.com/mrene/minidsp-rs/blob/dev/minidsp/src/bin/minidsp/main.rs"
    click Protocol "https://github.com/mrene/minidsp-rs/blob/dev/protocol/src/lib.rs"
    click HID "https://github.com/mrene/minidsp-rs/blob/dev/minidsp/src/transport/hid/mod.rs"
    click Net "https://github.com/mrene/minidsp-rs/blob/dev/minidsp/src/transport/net/mod.rs"
    click WS "https://github.com/mrene/minidsp-rs/blob/dev/minidsp/src/transport/ws/mod.rs"
    click Mock "https://github.com/mrene/minidsp-rs/blob/dev/minidsp/src/transport/mock/mod.rs"
    click Devtools "https://github.com/mrene/minidsp-rs/blob/dev/devtools/src/main.rs"
    click Docs "https://github.com/mrene/minidsp-rs/blob/dev/docs/build.sh"
    click Pipeline "https://github.com/mrene/minidsp-rs/blob/dev/.github/workflows/push-test.yml"
    click Pipeline "https://github.com/mrene/minidsp-rs/blob/dev/.github/workflows/release-build.yml"

    %% Styles
    classDef runtime fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef shared fill:#98FB98,stroke:#000,stroke-width:1px
    classDef transport fill:#FFA500,stroke:#000,stroke-width:1px
    classDef build fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef external fill:#FFF,stroke:#000,stroke-width:2px
```
