initial state: muzick music player + recommendation engine

docs/architecture/01-system-overview.md

@@ -0,0 +1,52 @@
+# 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.