User & Taste Onboarding
Relevant source files
The following files were used as context for generating this wiki page:
User & Taste Onboarding is a multi-step verification and configuration process designed to transition a newly authenticated user into an active participant within the Kocteau ecosystem. The process is divided into two primary phases: Profile Onboarding, where users establish their public identity, and Taste Onboarding, where users provide initial signals to seed the recommendation engine.
The flow is strictly sequential and state-dependent. A user cannot proceed to taste onboarding without a completed profile, and they cannot access the personalized "For You" feed until taste signals are established. This system ensures that the human-led music discovery loop starts with high-quality user metadata and explicit preferences.
Sources: README.md:65-71, apps/web/app/(auth)/onboarding/page.tsx:64-70
Architecture and Workflow
The onboarding system utilizes Next.js App Router for page-level transitions and client-side React components for complex state management and interactive forms. Data persistence is handled via Supabase, targeting the profiles and user_preference_tags tables.
High-Level Onboarding Flow
The following diagram illustrates the logical progression from initial authentication to the final application state.
Profile Onboarding Phase
The Profile Onboarding phase focuses on establishing a user's unique identity. Until this phase is completed, the profiles.username field remains nullable and the profiles.onboarded boolean is false.
Sources: README.md:52, apps/web/components/auth/profile-onboarding-flow.tsx:280-290
Steps and Validation
The ProfileOnboardingFlow component manages a four-step internal state machine:
| Step | Data Field | Description | Validation Rules |
|---|---|---|---|
| Name | display_name | Public name for reviews. | Minimum 2 characters. |
| Handle | username | Unique searchable handle. | 3-20 chars; a-z, 0-9, and _ only. |
| Avatar | avatar_url | Profile image or preset. | Disc presets or custom image upload. |
| Bio | bio | Short taste note. | Maximum 280 characters. |
Sources: apps/web/components/auth/profile-onboarding-flow.tsx:48-93
Avatar Management
Users can choose between uploading a custom image (handled via AvatarCropDialog) or selecting from a set of curated "Kocteau discs" presets. Custom uploads are stored in the Supabase avatars bucket with two versions: avatar-master.webp and avatar-thumb.webp.
Sources: apps/web/components/auth/profile-onboarding-flow.tsx:165-190, apps/web/components/auth/onboarding-flow-preview.tsx:400-430
Taste Onboarding Phase
Taste Onboarding gathers explicit preferences to solve the "cold start" problem for recommendations. This phase is handled by the TasteOnboardingForm component.
Sources: apps/web/app/(auth)/onboarding/taste/page.tsx:64-70, README.md:144-150
Signal Selection
Users must select a minimum of three taste signals (tags) from categories such as Genre, Mood, Scene, and Style. These tags are fetched from the preference_tags table.
Preference Weighting Logic
When preferences are saved, the system applies specific weights to different tag types to influence the recommendation algorithm. For example, "genre" tags are assigned a higher weight than other signal types.
| Tag Kind | Source | Weight |
|---|---|---|
genre | onboarding | 1.2 |
| Other | onboarding | 1.0 |
Sources: apps/web/app/api/preferences/taste/route.ts:85-90
API and Data Schema
Taste Preference Endpoint
POST /api/preferences/taste
- Authentication: Required.
- Rate Limiting: Enforced via
saveTastePreferenceswindow. - Validation: Uses
tasteOnboardingSchema(Zod). - Behavior: Performs a hard reset of existing onboarding tags before inserting new selections.
Sources: apps/web/app/api/preferences/taste/route.ts:16-50, apps/web/app/api/preferences/taste/route.ts:92-108
Database Interaction Summary
The onboarding process interacts primarily with these schema elements:
| Table | Operations during Onboarding |
|---|---|
profiles | upsert (display_name, username, avatar_url, bio, onboarded: true, taste_onboarded: true) |
preference_tags | select (featured tags for user selection) |
user_preference_tags | delete (resetting) and insert (saving user choices) |
analytics_events | insert (track taste_onboarding_completed) |
Sources: apps/web/app/api/preferences/taste/route.ts:74-142, README.md:204-224
Onboarding Preview System
For testing and design iteration, the project includes an OnboardingFlowPreview and OnboardingPreviewSwitcher. These components simulate the onboarding experience using static previewTags and initialDraft states, allowing for UI polish without mutating real database records.
Sources: apps/web/components/auth/onboarding-flow-preview.tsx:121-140, apps/web/components/auth/onboarding-preview-switcher.tsx:77-100
Conclusion
User & Taste Onboarding is critical to the Kocteau experience, as it transforms anonymous auth sessions into personalized profiles. By enforcing a structured sequence—identity first, then taste—the system ensures that every user entering the "For You" feed has the necessary graph data to receive relevant human-led music discovery.
Sources: AGENTS.md:33-41, README.md:144-146