Introduction to Kocteau
Relevant source files
The following files were used as context for generating this wiki page:
Kocteau is an open-source music review and taste discovery application designed for real listeners. It prioritizes human taste and quiet discovery over traditional social media noise, positioning itself as a hybrid system where human input serves as the source material and lightweight algorithms act as the routing layer. Sources: README.md:16-18, README.md:275-277
The project is structured as a monorepo with a primary focus on the web platform (apps/web), while a mobile application (apps/mobile) remains a future-facing target. It provides a personalized experience through a "For You" feed, editorial curation, and a structured onboarding process that captures user taste signals. Sources: CONTRIBUTING.md:3-4, README.md:65-68, AGENTS.md:10-14
Product Loop and User Flow
The core experience of Kocteau is built around a specific product loop designed to convert initial authentication into long-term discovery.
- Authentication: Users enter via email OTP (One-Time Password).
- Onboarding: Users complete a profile and select initial taste signals (preference tags).
- Creation: Users search for music via the Deezer API and publish reviews.
- Interaction: Users engage with the community through likes, bookmarks, follows, and comments.
- Personalization: The "For You" feed improves based on these behavioral signals.
Sources: README.md:65-75, AGENTS.md:32-41
Authentication Flow
Kocteau utilizes a code-only OTP flow powered by Supabase Auth and Resend.
The application specifically avoids magic links, requiring users to verify tokens within the Kocteau interface to prevent confusing loopbacks. Sources: README.md:195-201, apps/web/emails/README.md:15-18
Technical Stack
The application is built on a modern TypeScript stack with a heavy reliance on the Supabase ecosystem for backend services.
| Component | Technology |
|---|---|
| Frontend Framework | Next.js (App Router), React |
| Language | TypeScript |
| Styling | Tailwind CSS + shadcn/ui |
| State Management | TanStack Query (Client Cache) |
| Backend/Database | Supabase (Postgres, Auth, Storage, RLS, RPC) |
| React Email + Resend SMTP | |
| Music Catalog | Deezer Search API |
Sources: README.md:77-88, AGENTS.md:62-72
Data Architecture
Kocteau's data model is centered around music entities and user-generated reviews. The system uses Row Level Security (RLS) and Postgres functions (RPCs) to handle sensitive operations and recommendations.
Core Database Entities
The schema includes several key tables for managing the music graph:
profiles: User accounts and metadata.entities: Tracks and albums sourced from external providers.reviews: User-generated ratings and written takes.preference_tags: Taxonomy used for onboarding and recommendations.starter_tracks: Curated editorial picks for cold-start scenarios.
Sources: README.md:167-186
Recommendation System Logic
The "For You" feed is generated via a Supabase RPC that aggregates multiple inputs to rank content.
Sources: README.md:213-228
Design and Interface Principles
Kocteau follows a specific visual direction described as "dark, editorial, and minimal." The intent is to feel closer to a quiet music journal or Apple Music editorial than a standard SaaS dashboard.
Visual Constraints
- Color: Primarily monochrome. Color is used with restraint, limited to ratings (stars) or album art.
- Typography: Restrained contrast and stable geometry to avoid layout shifts.
- Motion: Used only when it improves clarity (via
motion/react).
Sources: AGENTS.md:83-116
Layout Hierarchy
The interface is structured to prioritize the "main event"—the music review.
- Sidebar: Stable navigation and primary actions.
- Center Column: The primary reading flow (Feed, Search, Reviews).
- Right Rail: Editorial companion containing starter picks and trends.
Sources: AGENTS.md:126-140
Development and Contribution
The project is "local-first" for contributors, utilizing the Supabase CLI to run a full local stack via Docker.
Local Setup Commands
pnpm install
pnpm supabase:start
pnpm supabase:reset
pnpm dev:web
Sources: CONTRIBUTING.md:19-25, README.md:135-144
Contribution Guidelines
The project maintains strict standards for contributions:
- Scope: PRs should be narrow and focused (e.g., UI polish, bug fixes).
- Sensitive Areas: Changes to Auth, Supabase schema, or recommendation logic require maintainer discussion.
- Releases: Versioning and changelogs are automated via "Release Please" based on conventional commit titles.
Sources: CONTRIBUTING.md:7-17, CONTRIBUTING.md:46-56, README.md:265-267
Security and Support
Security is managed through private vulnerability reporting. Sensitive areas include the Supabase RLS policies and API routes that handle data writes. The project explicitly forbids the inclusion of production secrets (service role keys, SMTP credentials) in the repository or documentation. Sources: SECURITY.md:3-12, SECURITY.md:25-30
Support is categorized into bug reports, feature requests (tied to the music review loop), and security disclosures via GitHub's private reporting tools. Sources: SUPPORT.md:5-15