muzick/docs/architecture/04-frontend-spec.md

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.