High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Kocteau is a music review and taste discovery platform designed with a "dark, editorial, human-led" aesthetic. The system is built as a monorepo that prioritizes a web-first experience, leveraging a modern TypeScript stack and a hybrid recommendation engine that combines user taste signals with editorial curation.
The architecture centers on a "Product Loop" where users authenticate via email OTP, establish taste signals, and engage with a personalized "For You" feed. The system emphasizes human taste as the primary source material, routed through lightweight algorithms rather than heavy social networking features.
Sources: AGENTS.md:7-14, README.md:16-19, CONTRIBUTING.md:4-6
System Core Stack
Kocteau utilizes a centralized stack focused on Next.js and Supabase. The architecture defaults to Server Components where possible to optimize performance, reserving Client Components for interactive elements like forms, live search, and optimistic UI updates.
| Layer | Technology |
|---|---|
| Framework | Next.js (App Router), React 19, TypeScript |
| Styling | Tailwind CSS, shadcn/ui, motion/react (framer-motion) |
| Backend/BaaS | Supabase (Auth, Postgres, Storage, RLS, RPCs) |
| State/Data | TanStack Query (React Query) |
| External APIs | Deezer Search API |
| Emails | React Email, Resend (via Supabase SMTP) |
Sources: AGENTS.md:76-85, README.md:121-131, apps/web/package.json:23-53
Application Data Flow
The application follows a strict data flow model where sensitive writes are handled through Server Actions or Supabase RPCs. The frontend communicates with Supabase using the @supabase/ssr package, respecting Row Level Security (RLS) policies defined in the database.
Authentication & Onboarding Flow
The authentication system is "OTP-first," removing the need for traditional passwords.
Recommendation Engine
The "For You" feed is the primary signed-in experience. It aggregates multiple data points to route music to the user.
Sources: README.md:237-251, AGENTS.md:180-188
Domain Model & Database Schema
The system architecture relies on several core entities stored in Supabase Postgres. RLS is used to protect these tables, ensuring users can only modify their own reviews, likes, and follows.
- Profiles: Extends auth with
username,display_name, andis_officialstatus. - Entities: Represents music units (tracks/albums) with
providerandprovider_id(Deezer). - Reviews: The central unit of the product; includes
ratingand written content. - Interaction Tables:
review_likes,review_bookmarks,review_comments, andprofile_follows. - Curation/Taste:
preference_tags,starter_tracks, andeditorial_collections.
Sources: README.md:214-233, AGENTS.md:195-207
Layout & Component Architecture
The visual architecture follows a "Reading Flow" priority. The layout is structured to keep reviews at the top of the hierarchy.
Layout Structure
- Primary Column (Center): Carries the main feed, search filters, and review content.
- Left Sidebar: Contains navigation and primary actions (Review/Search).
- Right Rail: Reserved for editorial discovery (Editor's Picks, Recently Discussed) rather than generic social metrics.
Sources: AGENTS.md:121-131, AGENTS.md:144-153
Technical Component Splits
Components are organized by "Product Intent" rather than just UI fragments:
review-card: Displays the primary content unit.review-composer: Handles create/edit logic.global-launcher: Managed byCmd+K(Search) orN(New Review) shortcuts.editorial-rail: Manages the companion discovery modules.
Sources: AGENTS.md:214-233, AGENTS.md:168-176
Operational Architecture
Kocteau uses a monorepo structure managed by pnpm and turbo.
Sources: CONTRIBUTING.md:4-6, package.json:11-15, turbo.json
Automated Release Flow
The project uses Release Please to automate versioning. It parses PR titles (e.g., feat(web): ... or fix(web): ...) to generate CHANGELOG.md and GitHub Releases upon merging to the main branch.