# System Overview

## High-Level Architecture

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

```mermaid
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.