Social Interactions & Graph

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• README.md
• apps/web/app/(main)/review/[id]/page.tsx/review/%5Bid%5D/page.tsx)
• apps/web/components/feed-review-list.tsx
• apps/web/app/(main)/u/[username]/page.tsx/u/%5Busername%5D/page.tsx)
• apps/web/components/recommendation-health-summary.tsx

Social interactions in Kocteau serve as the primary engine for music discovery and the construction of a human-led recommendation graph. Unlike generic social networks, Kocteau's social features—likes, follows, bookmarks, and comments—are designed to support discovery, establish trust between listeners, and improve the quality of the "For You" feed.

The system operates as a hybrid music discovery layer where human taste acts as the source material and lightweight algorithms route that taste to relevant users. Social signals are explicitly used as inputs for recommendation RPCs, transforming individual listening notes into a collective discovery network.

Sources: AGENTS.md:12-18, README.md:143-146

Core Interaction Mechanics

The social graph is built upon several key interactive primitives that allow users to engage with reviews and other listeners. These interactions are restricted to authenticated users.

User Interaction Types

Interaction	Description	Impact on Graph
Follow	Subscribing to a profile's updates.	Direct input for "Following" feed and "author_affinity" recommendations.
Like	Positive sentiment on a specific review.	Increases "popular_recent" weight and influences "For You" ranking.
Bookmark	Saving a review or entity for later.	Private library addition; used as a signal for personal recommendation tuning.
Comment	Threaded replies to music reviews.	Enhances engagement signals for review quality and discussion density.

Sources: README.md:73-77, AGENTS.md:218-223, apps/web/components/feed-review-list.tsx:44-51

Data Flow of Social Signals

The following diagram illustrates how user actions are processed to update the social graph and recommendation engine.

The Recommendation Graph

The social graph is not just a list of connections; it is a weighted system that determines content delivery in the primary "For You" surface. The graph uses explicit and inferred signals to establish "affinity" between users.

Recommendation Inputs

The system identifies several "reasons" for content appearing in a user's feed, many of which are derived from social graph data:

• Following: Content from users explicitly followed.
• Author Affinity: Content from listeners who share similar tastes or have been interacted with previously.
• Taste Match: Alignment between a user's onboarding tags and the tags of a reviewed entity.
• Popular Recent: High-engagement content (likes/comments) within the broader network.

Sources: apps/web/components/feed-review-list.tsx:44-51, README.md:143-155

Analytics and Health

Kocteau tracks the performance of the social graph through specific metrics to ensure the "For You" loop remains healthy. This includes monitoring the "Review Open Rate" and "Fallback Rate" (when the personalized graph is too sparse and returns latest reviews instead).

Sources: apps/web/components/recommendation-health-summary.tsx:112-135, README.md:155-157

Technical Implementation

Public Profile Bundle

Profiles serve as the nodes in the social graph. When viewing a profile, the system fetches a "Public Bundle" that includes social state relevant to the current viewer.

// Derived from apps/web/app/(main)/u/[username]/page.tsx
const { profile, pinnedReview, reviews } = publicBundle;
const isOwnProfile = user?.id === profile.id;

const [ { likedReviewIds, bookmarkedReviewIds }, isFollowing ] = await Promise.all([
  getProfileViewerState(user?.id, reviewIds),
  getViewerFollowsProfile(user.id, profile.id)
]);

Sources: apps/web/app/(main)/u/[username]/page.tsx:81-99

Threaded Discussions

Social interaction also manifests through the ReviewCommentsPanel. This component manages the "listening notes" discussion, allowing users to reply to reviews and mention authors, which triggers notifications and adds density to the interaction graph.

Sources: apps/web/app/(main)/review/[id]/page.tsx:135-153, README.md:182

Conclusion

The Social Interactions & Graph system in Kocteau is a utility-focused architecture designed to facilitate human-led discovery. By strictly tying social actions (likes, follows, bookmarks) to the recommendation engine, the project ensures that social features serve the primary goal of music discovery rather than generic social networking.