kami
46 lines
2.2 KiB
Markdown
46 lines
2.2 KiB
Markdown
# 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.
|