kami
53 lines
1.8 KiB
Markdown
53 lines
1.8 KiB
Markdown
# 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.
|