# muzick

A high-performance, distributed music orchestration and recommendation platform.

## Overview

**muzick** is designed to manage a local music library while providing an "infinite vibe" listening experience. It bridges the gap between a local filesystem and advanced discovery engines through a tiered recommendation architecture.

## Tech Stack

### **Frontend**
- **Framework:** React
- **Routing:** TanStack Router
- **Data Fetching:** TanStack Query (with Look-ahead Buffering)
- **State Management:** Zustand (for Session/Vibe state)
- **Styling:** CSS Variables (Customizable Themes)

### **Backend**
- **Runtime:** Node.js / TypeScript
- **Framework:** Fastify
- **Task Queue:** BullMQ (via Redis)
- **Search:** Typesense

### **Infrastructure & Data**
- **Database:** PostgreSQL (Source of truth for metadata, relationships, and session state)
- **Cache/Queue:** Redis
- **Audio Analysis:** Essentia (via Worker processes)
- **External Metadata:** MusicBrainz, Discogs, LRCLib, Cover Art Archive

## Core Concepts

- **The Rolling Vibe:** A continuous, evolving stream of music that uses a "Rolling Window" of tracks. It interleaves owned library tracks with high-probability "probation" tracks (external discoveries).
- **The Dislike Lifecycle:** A multi-stage state machine that protects users from accidental deletions while ensuring the library stays clean.
- **Tiered Similarity:** Instant metadata-based matches, followed by deep audio-feature similarity.

## Getting Started

### Prerequisites
- Docker & Docker Compose

### Running Locally

Vibe uses the same per-user identity convention as the rest of the API:
`x-user-id` when supplied, otherwise the local default user. Each user's Vibe
session and listening history are isolated from other users.

```bash
docker-compose up -d
```