initial state: muzick music player + recommendation engine

2026-07-14 01:35:52 +04:00
commit 737bf19fd1
196 changed files with 32431 additions and 0 deletions
@@ -0,0 +1,45 @@
+# Frontend Specification
+
+## Core Technology Stack
+- **Framework:** React (Vite-based)
+- **Routing:** TanStack Router (Type-safe routing)
+- **Data Fetching:** TanStack Query (Managing server state & caching)
+- **State Management:** Zustand (Managing local client-side playback and vibe state)
+- **Styling:** CSS Variables (Enabling easy theme switching)
+
+## 1. Key UI Patterns
+
+### **The "Look-ahead Buffer" (Seamless Playback)**
+To prevent playback gaps, the frontend implements a **Prefetching Queue**.
+- **Mechanism:** The client maintains a `playback_buffer` in Zustand containing the next 20 tracks.
+- **Implementation:** When the user reaches track $N$, TanStack Query triggers a fetch for the next chunk ($N+20$) in the background.
+- **User Experience:** Tapping "next" is near-instantaneous as the track is already in memory.
+
+### **The "Vibe" Interface**
+The core feature is the **Active Vibe Page**.
+- **Visuals:** Shows the current "Rolling Window" as a progress bar/timeline.
+- **Real-time Updates:** Displays "Incoming Recommendations" (Probation tracks) as they are discovered.
+- **Controls:** Quick-access "Keep" / "Dislike" buttons that trigger the lifecycle state machine.
+
+### **The "Quarantine" Page**
+A management view for the `PENDING_REMOVAL` state.
+- **Features:** List of hidden tracks, "time remaining" timers, and "Restore" / "Delete" actions.
+
+## 2. State Management Strategy
+
+### **Zustand Stores**
+- **`usePlaybackStore`:** Tracks `current_track`, `playback_position`, `is_playing`, and the `local_queue`.
+- **`useVibeStore`:** Manages the `active_session_id` and the current "Center Track" context.
+
+### **TanStack Query**
+- Used for all standard CRUD operations (Library, Artists, Albums).
+- Configured with aggressive `staleTime` for static data (Artists/Albums) and low `staleTime` for dynamic data (History/Stats).
+
+## 3. Navigation Structure
+
+- **Home:** Continue Listening, Recently Added, Recently Played.
+- **Library:** Artists, Albums, Tracks, Genres (hierarchical).
+- **Vibe:** The infinite player/discovery interface.
+- **Discover:** Manual exploration of similar artists/tracks.
+- **Search:** Global fuzzy search.
+- **Settings:** Theme, playback modes, and automation rules.