Feed & Recommendation Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Feed & Recommendation Engine is the core discovery mechanism of Kocteau. It transitions from a "cold-start" experience using curated editorial picks to a personalized "For You" feed driven by human taste signals, explicit preferences, and inferred behavioral data. The system utilizes lightweight algorithms to route human-authored music reviews to the most relevant listeners.
Sources: README.md:213-215, AGENTS.md:12-19
System Architecture
The engine is built on a hybrid architecture combining Postgres-based SQL logic (Supabase) for ranking and a React-based frontend for infinite scrolling and interaction tracking.
The diagram above illustrates the request flow from the client through the Next.js server to the Supabase RPC layer where the ranking logic resides.
Sources: apps/web/lib/queries/feed.ts:251-275, supabase/migrations/20260603143952_feed_tuning_v1.sql:20-25
Recommendation Logic (For You)
The personalized "For You" feed is powered by the get_recommended_review_ids SQL function. It aggregates multiple signal types to calculate a base_score for candidate reviews created within the last 365 days.
Scoring Factors
The system applies weights to various interactions and attributes to determine relevance:
| Factor | Weight/Influence | Source Signal |
|---|---|---|
| Entity Taste | 1.75x Multiplier | Match between entity tags and user preference tags |
| Author Taste | 0.9x Multiplier | Match between reviewer's profile tags and user preference tags |
| Follow Status | +2.25 Base Score | If the user follows the review author |
| Familiar Entity | 1.15x Multiplier | If user has previously liked/bookmarked the track |
| Review Depth | +0.12 to +0.85 | Character length (bonus for 120+ or 280+ chars) |
| Recency | Time Decay | 1 / (1 + days_old / 21.0) |
Sources: supabase/migrations/20260603143952_feed_tuning_v1.sql:138-164, README.md:217-226
Diversity and Penalty Logic
To prevent the feed from becoming repetitive, the engine applies "diversity pressure":
- Author Rank Penalty: Reduces the score by
0.55for each subsequent review from the same author in the result set. - Entity Rank Penalty: Reduces the score by
0.95for each subsequent review of the same track/entity. - Negative Signal: A penalty of
-2.4is applied if the user has previously rated the entity 2 stars or lower.
Sources: supabase/migrations/20260603143952_feed_tuning_v1.sql:174-188
Feed Modes and Fallbacks
The system supports multiple view modes. If the personalized recommendation fails, the system is designed to gracefully degrade to the "latest" reviews.
This flowchart details the logic used to determine which feed content to display based on user state and system health.
Sources: apps/web/lib/queries/feed.ts:273-294, apps/web/app/(main)/page.tsx:32-45
Cold-Start & Starter Picks
When a user is new or the recommendation graph is sparse, the engine provides "Starter Picks". These are curated editorial prompts stored in the starter_tracks table.
- Curated Logic: Starter tracks are ranked against onboarding tags using the
get_starter_tracksfunction. - Personalization: Uses
starter_track_tagsto align with the user's initial taste signals. - UI Integration: Displayed via
FeedStarterLayerorFeedStarterShelfif the main feed has fewer than 4 reviews.
Sources: apps/web/components/feed-review-list.tsx:432-446, README.md:231-240
Analytics and Health Monitoring
The engine includes a dedicated monitoring system ("Studio Health") to track the performance of the recommendation logic.
Key Performance Metrics
| Metric | Description |
|---|---|
| Fallback Rate | Percentage of feed loads that failed and reverted to "latest". |
| Review Open Rate | Ratio of review_open events to review_impression events. |
| Starter Conversion | Rate at which starter picks lead to a published review. |
| Read Depth | Tracks if a user scrolled through 50% or 90% of a review card. |
Sources: apps/web/lib/recommendation-health/metrics.ts:5-20, apps/web/components/feed-review-list.tsx:282-300, apps/web/components/recommendation-health-summary.tsx:112-132
Recommendation Reasons
Each recommended item is assigned a reason which is surfaced in the UI as an "eyebrow" label:
entity_taste: "In your lane"taste_match: "Taste match"following: "From your follows"familiar_entity: "Related pick"author_affinity: "Similar listener"popular_recent: "Popular now"
Sources: apps/web/components/feed-review-list.tsx:28-35, supabase/migrations/20260603143952_feed_tuning_v1.sql:190-205
Data Model
The recommendation engine primarily interacts with the following schema elements:
The Feed & Recommendation Engine prioritizes human taste and editorial quality over pure engagement metrics, using a SQL-heavy ranking approach to ensure low latency and high relevance within a minimal, dark-themed interface.