# coolcode/musix architecture

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

- Interactive diagram: https://gitdiagram.com/coolcode/musix
- Repository: https://github.com/coolcode/musix

## Overview

##### Project Type and Purpose
- MUSIX is a single-binary, terminal-based MP3 player written in Rust.
- It provides a full TUI (text-based UI), a playback engine, and uses external crates for audio decoding and rendering.

##### High-Level File Structure Analysis
- Top-level:
- Cargo.toml / Cargo.lock – Rust project manifest, dependencies (rodio, ratatui, crossterm, rand)
- src/main.rs – Entire application entry point (~700 lines)
- data/ – Local folder for MP3 files (mirror of ~/Music)
- .github/workflows/ – CI/CD pipelines (build, test, release)
- rustfmt.toml – Formatting rules
- README.md, LICENSE – Documentation and licensing
- No separate “backend” or “frontend” directories; all logic lives in main.rs but can be conceptually split into modules (UI, player engine, audio engine).

##### Key Architectural Insights from README
- Three primary subsystems:
a. Terminal UI (ratatui + crossterm)
b. Player Engine (state management, controls, fuzzy search)
c. Audio Engine (rodio for MP3 decoding/playback)
- Data sources: local filesystem (`~/Music` and `./data`)
- CI/CD integration: GitHub Actions workflows

##### Components
a. UI Layer (TUI)
- ratatui: layout, panels, progress bar
- crossterm: keyboard input, terminal control
b. Player Engine
- State machine for play/pause, shuffle, seeking
- Fuzzy search logic using custom scoring
- Keyboard command dispatcher
c. Audio Engine
- rodio: MP3 decoding, audio output
- Interaction with OS audio subsystem (ALSA on Linux, CoreAudio on macOS)
d. Data Sources
- Local filesystem watcher/reader for `~/Music` and `./data`
e. CI/CD & Tooling (optional sidebar)
- GitHub Actions (test.yml, release.yml)
- rustfmt, clippy

##### Relationships and Data Flows
1. User presses a key → crossterm captures event → UI Layer
2. UI Layer updates view, forwards commands to Player Engine
3. Player Engine updates internal state, chooses track, handles seek/shuffle logic
4. Player Engine calls Audio Engine (rodio) to load file and stream PCM to OS audio
5. Audio Engine pushes frames to OS audio subsystem → speakers
6. Player Engine emits playback status → UI Layer updates progress bar and status panel

##### Architectural Patterns and Principles
- Layered architecture: UI → domain (player engine) → infrastructure (audio engine, filesystem)
- Event-driven input handling (keyboard events trigger state transitions)
- Separation of concerns: UI rendering vs. playback logic vs. audio I/O
- Minimal external surface: single binary simplifies deployment

## Diagram (Mermaid)

```mermaid
flowchart TB
    title["MUSIX vX.Y Architecture"]

    subgraph "UI Layer"
        UI["Terminal UI\n(ratatui + crossterm)"]:::ui
    end

    subgraph "Player Engine"
        PE["State Machine\nFuzzy Search\nCommand Dispatcher"]:::core
    end

    subgraph "Audio Engine"
        AE["rodio\nMP3 Decoding & Playback"]:::infra
    end

    Data["Local Filesystem\n(~/Music, ./data)"]:::external
    OS["OS Audio Subsystem\n(ALSA, CoreAudio)"]:::external

    subgraph "CI/CD & Tooling"
        CI_Test["GitHub Actions\nCI Pipeline"]:::infra
        CI_Release["GitHub Actions\nRelease Pipeline"]:::infra
        Manifest["Cargo.toml"]:::infra
        Format["rustfmt.toml"]:::infra
        README["README.md"]:::infra
        License["LICENSE"]:::infra
    end

    User["User"]:::external -->|"keyboard event"| UI
    UI -->|"play command"| PE
    PE -->|"load file"| AE
    AE -->|"PCM stream"| OS
    Data -->|"scan on startup"| PE
    PE -->|"status update"| UI

    title -.-> CI_Test
    title -.-> Manifest

    click UI "https://github.com/coolcode/musix/blob/main/src/main.rs"
    click PE "https://github.com/coolcode/musix/blob/main/src/main.rs"
    click AE "https://github.com/coolcode/musix/blob/main/src/main.rs"
    click Data "https://github.com/coolcode/musix/tree/main/data/"
    click CI_Test "https://github.com/coolcode/musix/blob/main/.github/workflows/test.yml"
    click CI_Release "https://github.com/coolcode/musix/blob/main/.github/workflows/release.yml"
    click Manifest "https://github.com/coolcode/musix/blob/main/Cargo.toml"
    click Format "https://github.com/coolcode/musix/blob/main/rustfmt.toml"
    click README "https://github.com/coolcode/musix/blob/main/README.md"
    click License "https://github.com/coolcode/musix/tree/main/LICENSE"

    classDef ui fill:#D0E6FF,stroke:#0366d6;
    classDef core fill:#D0FFD6,stroke:#28a745;
    classDef infra fill:#FFE5B4,stroke:#d9822b;
    classDef external fill:#F0F0F0,stroke:#888888,stroke-dasharray:5 5;
```
