muzick/docs/architecture/03-backend-spec.md

Backend Specification

Core Technology Stack

• Runtime: Node.js (TypeScript)
• Framework: Fastify
• Communication: REST API (primary)
• Queueing: BullMQ with Redis

1. API Architecture

Library Management

• GET /api/tracks: Paginated list of tracks (supports sort/filter).
• GET /api/tracks/{id}: Full track metadata.
• GET /api/search?q={query}: Fuzzy search via Typesense.
• POST /api/library/reindex: Manual trigger for the indexing worker.

The Vibe Engine (Recommendation)

• GET /api/vibe: Returns a Sequence Chunk of track IDs.
  • Client Implementation: Uses TanStack Query to implement a "Look-ahead Buffer."
• GET /api/vibe/from-genre?genre={id}: Generates a session based on a specific genre.

The Lifecycle (Dislike/Removal)

• POST /api/dislike/{track_id}: Moves track to PENDING_REMOVAL (State: HIDDEN).
• DELETE /api/dislike/{id}: Restores track to LIBRARY.
• GET /api/dislikes: Lists all tracks in the quarantine.
• POST /api/dislikes/sweep: Manual trigger for the background cleanup worker.

Session Management

• GET /api/sessions/current: Returns the metadata for the current ACTIVE recommendation batch.
• POST /api/sessions/heartbeat: Updates last_interaction_at for the active batch.

2. The "Rolling Window" Algorithm

To provide an infinite, evolving stream, the backend implements a Stateful Sequence Generator.

Algorithm Steps:

1. Seed Selection: Identify the center_track_id (the last successfully played track).
2. Candidate Generation:
   • Primary (80%): Fetch tracks similar to the center_track_id (Metadata + Audio Feature match).
   • Discovery (20%): Fetch tracks from the Probation Pool (newly acquired recommendations).
3. Sequence Construction:
   • Group results into a "Chunk" (e.g., 20 tracks).
   • Apply Batch Rules:
     • Max 1 song per artist in a single chunk.
     • Max 2 songs per genre in a single chunk.
     • Mix in "probation" tracks at a controlled rate.
4. Response: Return a JSON array of track objects with pre-calculated sequence order.

3. Business Logic Invariants

• The "No Ghost" Rule: The backend MUST verify file existence before returning a track in a Vibe sequence.
• The "Success-Driven Center" Rule: The center_track_id is updated ONLY when a track's completed flag is set to true via /api/history.
• The "Atomicity" Rule: All state transitions (e.g., PENDING_REMOVAL \rightarrow DELETED) must be handled within a database transaction.