# derekcorniello/8bitbeats architecture

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

- Interactive diagram: https://gitdiagram.com/derekcorniello/8bitbeats
- Repository: https://github.com/derekcorniello/8bitbeats

## Overview

##### Project Type and Purpose
- 8BitBeats is a standalone, terminal-based open-source tool written in Rust.
- Its purpose is to generate, customize, and replay reproducible 8-bit/chiptune music via a TUI (Terminal UI) and audio playback.

##### File Structure
- Cargo.toml: declares dependencies and binaries.
- src/
- main.rs      – application entry point, orchestrates subsystems.
- tui.rs       – Terminal UI layer (ratatui + crossterm).
- gen.rs       – Core music generation engine (random/seeding, uses rust-music-theory + rand).
- melodies.rs  – Definitions of melody patterns or scales.
- progs.rs     – “Program” definitions—instrument settings for playback.
- No separate frontend/backend directories—everything compiles into one binary.
- Crossbeam-channel indicates a multi-threaded, producer–consumer architecture between generation, playback, and UI.

##### Key Insights from README
- UI navigation and playback controls are handled in tui.rs.
- Music generation: deterministic track ID → gen.rs + melodies.rs → sequence of notes.
- Audio playback: rodio + progs.rs → audio thread.
- Dependencies reveal the stack: ratatui/crossterm (TUI), rand (randomness), rust-music-theory (scales), rodio (sound), crossbeam-channel (threading).

##### Components
a. Main Components
- User (keyboard)
- TUI Layer (tui.rs; ratatui + crossterm)
- Controller/Orchestrator (main.rs)
- Generation Engine (gen.rs + melodies.rs)
- Playback Engine (progs.rs + rodio)
- Data Channels (crossbeam-channel)
- External Crates/Services
b. Relationships & Data Flows
1. User input → TUI Layer
2. TUI Layer emits commands/events → Controller
3. Controller forks:
– Generation request → Generation Engine → Emits note sequences with track ID
– Playback control → Playback Engine
4. Generation Engine → pushes sequences via channel → Playback Engine
5. Playback Engine → streams audio to OS sound API
6. Controller updates TUI status (play/pause/progress)
c. Architectural Patterns & Principles
- Modular separation: UI vs. Logic vs. Audio
- Producer–Consumer via channels for decoupling generation from playback
- Deterministic ID → Pure-function generation for reproducibility
d. Key Technologies & Libraries
- ratatui + crossterm: building and rendering the interactive TUI
- rand + rust-music-theory: parameterized, seeded music generation
- crossbeam-channel: thread-safe message passing
- rodio: low-latency audio playback

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interaction
    User["User (Keyboard)"]:::external
    User -->|"input"| TUI

    %% UI Layer
    TUI["TUI Layer\n(src/tui.rs)\n• ratatui + crossterm"]:::ui
    TUI -->|"events"| Controller

    %% Controller
    Controller["Controller / Orchestrator\n(src/main.rs)"]:::ctrl
    Controller -->|"generation request"| GenEngine
    Controller -->|"playback control"| Playback

    %% Generation Flow
    GenEngine["Generation Engine\n(src/gen.rs)\n• rand\n• rust-music-theory"]:::gen
    GenEngine -->|"note sequence via channel"| Channel

    Melody["Melody Definitions\n(src/melodies.rs)"]:::gen
    GenEngine -->|"uses patterns"| Melody

    %% Channel
    Channel["crossbeam-channel"]:::ext
    Channel -->|"stream notes"| Playback

    %% Playback Flow
    Playback["Playback Engine\n(src/progs.rs)\n• rodio"]:::play
    Playback -->|"audio stream"| Audio

    Audio["OS Audio API"]:::external

    %% Status Updates
    Playback -->|"status update"| Controller
    Controller -->|"UI update"| TUI

    %% External Crates Group
    subgraph "External Crates" 
        Rata["ratatui"]:::ext
        Cros["crossterm"]:::ext
        Rand["rand"]:::ext
        Theory["rust-music-theory"]:::ext
        Crossbeam["crossbeam-channel"]:::ext
        Rodio["rodio"]:::ext
    end

    Rata --> TUI
    Cros --> TUI
    Rand --> GenEngine
    Theory --> GenEngine
    Crossbeam --> Channel
    Rodio --> Playback

    %% Documentation & Manifest
    Manifest["Cargo.toml"]:::doc
    Readme["README.md"]:::doc
    License["LICENSE"]:::doc

    Manifest -->|"declares deps"| Controller
    Readme --> Controller
    License --> Controller

    %% Click Events
    click TUI "https://github.com/derekcorniello/8bitbeats/blob/main/src/tui.rs"
    click Controller "https://github.com/derekcorniello/8bitbeats/blob/main/src/main.rs"
    click GenEngine "https://github.com/derekcorniello/8bitbeats/blob/main/src/gen.rs"
    click Melody "https://github.com/derekcorniello/8bitbeats/blob/main/src/melodies.rs"
    click Playback "https://github.com/derekcorniello/8bitbeats/blob/main/src/progs.rs"
    click Manifest "https://github.com/derekcorniello/8bitbeats/blob/main/Cargo.toml"
    click Readme "https://github.com/derekcorniello/8bitbeats/blob/main/README.md"
    click License "https://github.com/derekcorniello/8bitbeats/tree/main/LICENSE"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#2b65ec;
    classDef gen fill:#d0f0c0,stroke:#2e8b57;
    classDef play fill:#ffdab9,stroke:#cd5c5c;
    classDef ext fill:#f2f2f2,stroke:#808080;
    classDef ctrl fill:#e6f7ff,stroke:#1e90ff;
    classDef external fill:#ffffff,stroke:#666666,stroke-dasharray: 2 2;
    classDef doc fill:#faf0e6,stroke:#b8860b;
```
