Supabase Integration
Relevant source files
The following files were used as context for generating this wiki page:
Kocteau utilizes Supabase as its primary backend-as-a-service provider, integrating its core offerings for database management, authentication, storage, and server-side logic. The architecture relies on a local-first development workflow using the Supabase CLI, transitioning to cloud-hosted services for production.
The integration covers the entire product loop, from OTP-based authentication and profile onboarding to personalized recommendations served via Postgres Functions (RPCs). High-level security is enforced through Row Level Security (RLS) policies and validated through local linting tools.
Sources: README.md:95-103, CONTRIBUTING.md:23-32
Core Architecture and Components
The system architecture is divided between the client-side Next.js application and the Supabase backend services. The connection is established via environment variables that define the API URL and public publishable keys.
Connection Management
Environment variables are managed through a utility layer to ensure the presence of required connection strings before initializing clients.
| Variable | Description | Source |
|---|---|---|
NEXT_PUBLIC_SUPABASE_URL | The API URL for the Supabase instance (Local: http://127.0.0.1:54321) | apps/web/lib/supabase/env.ts:1-7 |
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY | Public browser-safe key for client-side operations | apps/web/lib/supabase/env.ts:9-17 |
Service Configuration
The local Supabase environment is defined in supabase/config.toml, which configures the specific ports and behaviors for the Postgres database, Auth server, and Edge Runtime.
The diagram above shows the relationship between the web application tiers and the Supabase service modules.
Sources: supabase/config.toml:1-12, README.md:105-112
Authentication System
Kocteau implements an "OTP-first" authentication flow. It bypasses traditional password management in favor of 6-digit email codes delivered via SMTP.
Authentication Flow
- Request: User submits an email via
signInWithOtp. - Delivery: Supabase Auth sends a code using a customized template.
- Verification: The user enters the code in-app, which is verified against Supabase Auth.
- Onboarding: New users are directed to profile and taste onboarding sequences.
Email Configuration
The integration uses a specific "code-only" template to avoid confusing loops created by magic link buttons.
| Setting | Value | Description |
|---|---|---|
otp_length | 6 | Length of the numerical verification code |
otp_expiry | 3600 | Code validity duration in seconds (1 hour) |
enable_confirmations | true | Users must confirm email before signing in |
Sources: supabase/config.toml:156-173, apps/web/emails/README.md:12-25, README.md:208-217
Database and Data Access
The database layer uses PostgreSQL (version 17) with intensive use of Row Level Security (RLS) to manage data access.
Core Tables
The schema includes several key tables for the music review ecosystem:
profiles: User identity and onboarding status.reviews: Primary content containing ratings and text.entities: Tracks and albums sourced from Deezer.review_likes/review_bookmarks: User interactions with content.analytics_events: Internal product feedback tracking.
Data Mutation Example
Server-side mutations, such as deleting a review, involve a coordinated cleanup across multiple tables to maintain integrity, often handled within Next.js API routes using a Supabase server client.
Sequence of operations for a review deletion.
Sources: apps/web/app/api/reviews/[reviewId]/route.ts:245-295, README.md:180-200
Local Development Workflow
Kocteau prioritizes a local-first development cycle using the Supabase CLI to ensure contributors do not need production credentials.
CLI Commands
Contributors use a standard set of scripts to manage the local environment:
pnpm supabase:start: Boots the Docker-backed local stack (DB, Auth, Studio, Inbucket).pnpm supabase:reset: Re-applies migrations and loads seed data fromsupabase/seeds.pnpm supabase:types: Generates TypeScript definitions from the local schema.pnpm supabase:lint: Runs RLS and schema validation.
Seed Data
Local environments are populated with deterministic product configurations, including preference tags and editorial starter picks, defined in the config.toml seed section.
[db.seed]
enabled = true
sql_paths = ["./seeds/00_preference_tags.sql", "./seeds/10_editorial_starter_picks.sql"]
Sources: CONTRIBUTING.md:23-32, supabase/config.toml:68-73, package.json:23-30
Security and Governance
Security is centered on protected API access and environment variable hygiene.
- RLS Tests: Located in
supabase/tests/rls/, these ensure schema changes do not leak data. - Service Role: Production service role keys are never exposed to the frontend; they are reserved for controlled deployment environments.
- Rate Limiting: Implemented via Postgres tables (
rate_limit_windows) to prevent abuse without requiring external dependencies like Redis.
Sources: SECURITY.md:21-27, supabase/tests/rls/README.md:1-10, README.md:118-120
Summary
The Supabase integration provides a robust, type-safe backend for Kocteau. By leveraging Postgres-native features like RLS and RPCs alongside the Supabase Auth and Storage modules, the project maintains a minimal footprint while supporting complex features like personalized recommendations and secure user-generated content management.