Web APIs & Route Handlers
Relevant source files
The following files were used as context for generating this wiki page:
The Kocteau web architecture utilizes Next.js App Router handlers and server routes to manage data flow between the frontend and the Supabase backend. These APIs handle critical functions including music entity discovery via the Deezer Search API, personalized feed generation, and write-sensitive flows such as review creation and social interactions.
The system is designed with a "server-first" mentality, where complex logic and database interactions are encapsulated in server components or dedicated API routes, while the client focuses on interactive elements and optimistic updates using TanStack Query.
Sources: README.md:91-105, AGENTS.md:315-325
Architecture and Data Flow
Kocteau follows a structured data flow where the frontend communicates with internal API routes, which in turn interface with Supabase PostgreSQL functions (RPCs) and external providers.
API Communication Pattern
The diagram shows how client components use TanStack Query to fetch data from Next.js route handlers, which manage authentication and interface with the database or external APIs.
Sources: README.md:100-104, AGENTS.md:75-85
Core API Categories
Discovery and Search APIs
Kocteau integrates with the Deezer Search API to allow users to find tracks, albums, and artists. This data serves as the foundation for creating reviews. Search functionality is designed to be accessible to signed-out users, though performing actions like reviewing requires authentication.
Sources: README.md:105, AGENTS.md:200-210
Recommendation and Feed Handlers
The "For You" feed is powered by a personalized recommendation system. This involves complex RPCs (Remote Procedure Calls) within Supabase that process user taste tags, follows, and interaction history.
| Endpoint (Logical) | Purpose | Data Inputs |
|---|---|---|
/api/feed | Generates personalized or global music feeds | view (for-you, following, latest), cursor |
/api/starter/rail | Fetches editorial starter picks based on context | surface (home, track, profile), context |
/api/search | Interfaces with Deezer for entity discovery | q (query string), type |
Sources: apps/web/lib/starter/surface.ts:88-95, apps/web/components/feed-review-list.tsx:100-115, README.md:175-185
Starter Rail and Surface Context
The Starter Rail API provides curated content based on where the user is within the application. It uses a specific utility to map pathnames to "surfaces" and "context keys" to ensure recommendations are relevant to the current page.
export function getStarterRailQueryPath(pathname: string | null | undefined) {
const params = new URLSearchParams({
surface: getStarterSurfaceFromPathname(pathname),
context: getStarterContextKey(pathname),
});
return `/api/starter/rail?${params.toString()}`;
}
Sources: apps/web/lib/starter/surface.ts:88-95
Write-Sensitive Operations
Write operations are strictly controlled and typically routed through server routes to ensure security and proper Row Level Security (RLS) enforcement.
- Authentication: OTP-first flow using Supabase Auth.
- Social Actions: Likes, bookmarks, comments, and follows require authenticated sessions.
- Review Creation: Composition occurs on the client, but the final write is handled by a server route or Supabase RPC to ensure data integrity and uniqueness for music entities.
Sources: AGENTS.md:265-280, README.md:155-165
Analytics and Monitoring
The project includes a lightweight internal analytics API that records product feedback events without collecting sensitive personal data like emails or IPs.
Analytical Event Flow
The sequence shows how user actions trigger client-side tracking, which is then sent to a dedicated analytics endpoint and stored in the database.
Sources: apps/web/components/feed-review-list.tsx:165-185, README.md:209-224
Security and Rate Limiting
API routes are protected via several layers:
- Supabase RLS: Ensures users can only access or modify data they own.
- PostgreSQL Rate Limiting: Managed within Supabase to prevent API abuse without requiring an external Redis dependency.
- Auth Guards: API handlers check for valid Supabase sessions before processing write requests.
Sources: README.md:104, CONTRIBUTING.md:120-130, AGENTS.md:315-320
Conclusion
The Web APIs and Route Handlers in Kocteau form a robust bridge between the editorial-focused frontend and the Supabase-backed data layer. By leveraging Next.js Route Handlers for complex logic and external integrations (like Deezer), and utilizing Supabase RPCs for performance-critical recommendation flows, the system maintains a high degree of technical accuracy while supporting a minimal, human-led music discovery experience.