muzick/docs/architecture/01-system-overview.md

System Overview

High-Level Architecture

muzick follows a distributed architecture centered around a shared PostgreSQL database and a distributed task queue (BullMQ).

graph TD
    User((User)) --> Web[Frontend - React/Vite]
    Web --> API[Backend - Fastify]
    API --> DB[(PostgreSQL)]
    API --> Search[Typesense]
    API --> Cache[(Redis)]
    API --> Queue[BullMQ]
    
    subgraph Workers
        W1[Metadata Worker]
        W2[Essentia Audio Worker]
        W3[Cleanup/Sweep Worker]
    end
    
    Queue --> W1
    Queue --> W2
    Queue --> W3
    
    W1 --> DB
    W2 --> DB
    W3 --> DB
    W1 --> External[External APIs: MusicBrainz/Discogs]
    W2 --> Audio[/Filesystem/Music]

Component Roles

1. Frontend (The Interface)

• React/Vite: High-performance UI.
• TanStack Router/Query: Handles complex navigation and provides the Look-ahead Buffer for the continuous playback stream.
• Zustand: Manages the active "Vibe" session state and local playback queue.

2. Backend (The Brain)

• Fastify: High-throughput API server.
• Business Logic: Manages the Rolling Window recommendation algorithm, the Dislike State Machine, and the Session Management.
• Typesense: Provides ultra-fast fuzzy search across the entire library.

3. Workers (The Muscle)

• Metadata Worker: Orchestrates enrichment via MusicBrainz, Discogs, and LRCLib.
• Essentia Worker: Performs heavy CPU-bound audio feature extraction (BPM, Key, etc.).
• Sweep Worker: Handles periodic cleanup (Dislike \rightarrow Deletion) and filesystem-to-DB reconciliation.

4. Data Layer

• PostgreSQL: The ultimate source of truth for metadata, user preferences, and session history.
• Redis: Powers the task queue (BullMQ) and provides ephemeral session data.