First-Party Analytics System
Relevant source files
The following files were used as context for generating this wiki page:
The Kocteau First-Party Analytics System is a lightweight, privacy-focused event tracking framework integrated directly with the project's Supabase backend. Its primary purpose is to provide product feedback and monitor the health of the Recommendation System rather than performing invasive user surveillance. The system avoids collecting sensitive data such as email addresses, IP addresses, or user agents.
Sources: README.md:213-216, AGENTS.md:468-472
System Architecture and Data Flow
The analytics system operates across both client and server environments, utilizing a unified event schema to ensure consistency. Client-side components track user interactions (such as feed loads and review impressions), while server-side routes track critical actions like bookmarking or recommendation fallbacks.
The diagram shows the end-to-end flow from client-side triggers to persistence and subsequent health reporting in the Studio.
Sources: apps/web/components/feed-review-list.tsx:162-175, apps/web/app/api/reviews/[reviewId]/bookmark/route.ts:60-68, apps/web/components/recommendation-health-summary.tsx:112-115
Event Schema and Validation
Every event is validated against a strict Zod schema. This ensures that only allowed metadata keys are stored and that event types remain canonical.
Event Structure
| Field | Type | Description |
|---|---|---|
eventType | Enum | The canonical name of the event (e.g., feed_loaded, review_impression). |
source | String | The origin of the event, default is web. Format: ^[a-z0-9_:-]{2,80}$. |
metadata | Record | Key-value pairs of contextual data. Keys must be allowed via isAllowedAnalyticsMetadataKey. |
Sources: apps/web/lib/validation/schemas.ts:251-275
Metadata Restrictions
Metadata values are restricted to primitive types (string, number, boolean, null) or arrays of these primitives. This prevents the ingestion of complex, unvalidated objects that could lead to data bloat or security vulnerabilities.
Sources: apps/web/lib/validation/schemas.ts:237-249
Core Tracked Events
The system tracks specific product-loop events to measure engagement and discovery quality.
| Event Type | Trigger Point | Tracked Metadata |
|---|---|---|
feed_loaded | When a feed page (e.g., For You) is successfully rendered. | view, page_index, review_count, starter_count. |
review_impression | When a review card enters the viewport. | review_id, entity_id, reason, position. |
for_you_review_action | When a user bookmarks/likes a review from the For You feed. | action (e.g., bookmark), review_id. |
recommendation_fallback | When the personalized recommendation RPC fails. | Error context or fallback source. |
taste_onboarding_completed | When a user finishes selecting initial taste tags. | Tag counts or category selections. |
Sources: README.md:218-228, apps/web/components/feed-review-list.tsx:185-212, apps/web/app/api/reviews/[reviewId]/bookmark/route.ts:60-68
Engagement Measurement (Read Depth)
Kocteau implements advanced tracking for "Read Depth" to determine if users are actually consuming review content. This is achieved using IntersectionObserver and dwell time calculations.
This sequence illustrates the logic for triggering read-depth events based on scroll position and time spent on a review card.
Sources: apps/web/components/feed-review-list.tsx:47-51, apps/web/components/feed-review-list.tsx:241-285
Recommendation Health Reporting
Analytics data is aggregated via a Supabase RPC to populate the "Recommendation Health" dashboard in the Studio. This allows maintainers to monitor the effectiveness of various discovery signals.
Health Metrics
The RecommendationHealthSummary component visualizes the following metrics derived from the analytics_events table:
- Fallback Rate: The percentage of feed loads that defaulted to "Latest" due to recommendation failures.
- Review Open Rate: The conversion rate from review impressions to full review views.
- Starter Conversion: The rate at which "Starter Picks" lead to published reviews.
- Tag Coverage: Distribution of tracks across different preference kinds (genre, mood, era, etc.).
Sources: apps/web/components/recommendation-health-summary.tsx:132-155, apps/web/components/recommendation-health-summary.tsx:190-205
Implementation Details
Client-side Tracking
The trackAnalyticsEvent function is used within React components. For example, in FeedReviewList, impressions are tracked as pages are loaded:
// apps/web/components/feed-review-list.tsx
trackAnalyticsEvent({
eventType: "review_impression",
source: "feed:for-you",
metadata: {
review_id: review.id,
entity_id: review.entities?.id ?? null,
reason: review.recommendation_reason ?? null,
position: pageStartPosition + reviewIndex,
},
});
Sources: apps/web/components/feed-review-list.tsx:202-211
Server-side Tracking
Critical state changes are tracked on the server to ensure accuracy, even if the client disconnects immediately after an action.
// apps/web/app/api/reviews/[reviewId]/bookmark/route.ts
if (analyticsSource === "feed:for-you") {
await trackServerAnalyticsEvent(supabase, {
userId: auth.user.id,
eventType: "for_you_review_action",
source: analyticsSource,
metadata: {
action: bookmarked ? "bookmark" : "unbookmark",
review_id: reviewId,
},
});
}
Sources: apps/web/app/api/reviews/[reviewId]/bookmark/route.ts:60-69
Conclusion
The First-Party Analytics System provides the essential feedback loop required to refine Kocteau's discovery experience. By focusing on high-level interaction signals and recommendation health rather than individual user profiling, it maintains the project's "quiet" and "minimal" editorial feel while providing actionable data for software architects and curators.