kami
54 lines
2.5 KiB
Markdown
54 lines
2.5 KiB
Markdown
# 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.
|