Review System
Relevant source files
The following files were used as context for generating this wiki page:
The Review System is the core functional module of Kocteau, designed to facilitate a "human-led music review experience." It enables users to discover music through Deezer integration, express their taste through a 5-star rating system, and provide editorial context via written notes. Reviews serve as the primary unit of the platform, driving the discovery loop and personalized recommendations.
Sources: AGENTS.md:7-13, README.md:144-148
System Architecture and Data Flow
The system follows a Next.js App Router architecture, utilizing Server Components for initial data fetching (via Supabase) and Client Components for interactive elements like the review composer and interaction bars.
Review Creation Lifecycle
The creation process is split into two primary steps: searching for a track and composing the review. If an unauthenticated user attempts to publish, the system saves a draft to local storage and redirects them to the login flow.
Core Components
1. NewReviewForm
A stateful client component that manages the multi-step process of creating or editing a review. It handles Deezer search results, keyboard navigation for track selection, and optimistic UI updates when saving changes.
| State/Prop | Type | Description |
|---|---|---|
step | "search" | "compose" | Current UI state of the form. |
selected | DeezerResult | null | The music entity currently being reviewed. |
rating | number | null | 1-5 star rating value. |
mode | "create" | "edit" | Determines if the form creates new entries or updates existing ones. |
Sources: apps/web/components/new-review-form.tsx:63-86, apps/web/components/new-review-form.tsx:112-135
2. ReviewCard
A polymorphic presentation component used throughout the app (Feed, Profile, Track pages). It adapts its layout based on entityMode ("full", "inline", or "cover") and handles "copy tone" adjustments (default vs. balanced) based on text length to maintain editorial aesthetics.
Sources: apps/web/components/review-card.tsx:47-57, apps/web/components/review-card.tsx:94-102
Data Models and Entities
Reviews are linked to unique music entities identified by provider IDs (primarily Deezer).
Review Object Structure
| Field | Type | Description |
|---|---|---|
id | UUID | Unique identifier for the review. |
rating | Number | Star rating (stored as numeric/float). |
title | String? | Optional headline for the review. |
body | String? | Optional long-form listening notes. |
is_pinned | Boolean | Whether the review is pinned to the user's profile. |
entities | Object | Metadata for the track (title, artist, cover_url). |
Sources: apps/web/components/review-card.tsx:28-38, apps/web/lib/queries/reviews.ts:16-27
API and Server Logic
The system utilizes specialized API routes and server-side queries to manage review persistence and visibility.
Endpoints
- POST
/api/reviews: Creates a new review and triggersinferEntityPreferenceTagsFromReviewto update the recommendation engine. - PATCH
/api/reviews/[reviewId]: Updates title, body, rating, or pinned status. - DELETE
/api/reviews/[reviewId]: Removes the review and associated notifications, likes, and bookmarks.
Server-Side Data Fetching
The getPublicReviewById function utilizes Next.js unstable_cache with specific tags (reviews, review:[id]) to ensure high performance and precise revalidation.
Interaction and Social Features
Social features are secondary to the reviews themselves, designed to support discovery without overpowering the editorial feel.
- Likes & Bookmarks: Users can interact with reviews through an interaction bar.
- Comments: Each review page includes a
ReviewCommentsPanelfor threaded replies. - Pinned Reviews: Authors can pin a specific review to the top of their profile page.
Sources: apps/web/app/(main)/review/[id]/page.tsx:135-156, apps/web/app/(main)/u/[username]/page.tsx:142-160, AGENTS.md:15-18
Conclusion
The Kocteau Review System prioritizes a "quiet" and "minimal" interface, focusing on high-quality track identity and human sentiment. By combining structured data from Deezer with unstructured personal notes, it creates a hybrid discovery layer where social interactions (likes/follows) serve as signals to refine the "For You" recommendation loop.
Sources: AGENTS.md:103-110, README.md:144-150