Recommendation Feed
Status: Shipped
Overview
Section titled “Overview”The recommendation feed is the primary discovery surface for the Featured page. It presents a sectioned discovery layout built on the current interim recommendation model (see model.md):
Recommended: personalized or fallback-ranked feed, paginatedPopular: short-list preview of what is getting the most attentionUpcoming: short-list preview of near-term opportunities
Users can filter each section by type.
Endpoints
Section titled “Endpoints”GET /recommendations
Section titled “GET /recommendations”Returns the Recommended feed section.
Query Parameters
Section titled “Query Parameters”| Param | Type | Default | Description |
|---|---|---|---|
| limit | Int | 20 | Number of items to return |
| offset | Int | 0 | Pagination offset |
| type | EventType? | null | Filter by EVENT or GIG. Null returns both (blended) |
| search | String? | null | Non-semantic keyword filter applied before pagination |
Response
Section titled “Response”Returns { items, meta }, where items is an array of Event objects ranked by recommendation score. meta includes total, limit, offset, and rankingMode.
rankingMode values:
PERSONALIZEDPOPULARITY_FALLBACK
GET /recommendations/popular
Section titled “GET /recommendations/popular”Returns the Popular Featured preview section. Supports limit, offset, and type.
Supports limit, offset, type, and search.
Response shape: { items, meta }, where meta includes total, limit, and offset.
GET /recommendations/upcoming
Section titled “GET /recommendations/upcoming”Returns the Upcoming Featured preview section. Supports limit, offset, and type.
Response shape: { items, meta }, where meta includes total, limit, and offset.
Behaviors
Section titled “Behaviors”Blended Feed (default)
Section titled “Blended Feed (default)”When no type filter is applied, events and gigs are ranked together in a single list by recommendation score. The model does not impose a fixed ratio between events and gigs.
Filtered Feed
Section titled “Filtered Feed”When type=EVENT is specified, only events are returned. When type=GIG, only gigs. The ranking within the filtered set is still personalized.
Empty State
Section titled “Empty State”For new users with no interactions and no interests, the feed falls back to a popularity-based ranking (events sorted by total interaction count, then by recency).
Keyword Search
Section titled “Keyword Search”The Featured page may pass a keyword search query to the recommendation section endpoints. Keyword search is non-semantic and does not depend on embeddings. It narrows the Recommended, Popular, and Upcoming recommendation sections before pagination while preserving each section’s ranking model. The social Following lane is not part of keyword search because it is an activity feed rather than a recommendation endpoint.
Featured Page Composition
Section titled “Featured Page Composition”The Featured page loads the three recommendation endpoints independently so the personalized feed, popularity preview, and upcoming preview can fail or update independently without collapsing into a single blended response.
Scenarios
Section titled “Scenarios”S-FEED-1: Blended feed default
Section titled “S-FEED-1: Blended feed default”GIVEN user A has interactions with both events and gigsWHEN user A sends GET /recommendationsTHEN the response contains a mix of events and gigsAND items are ordered by personalized recommendation scoreS-FEED-2: Filter by event type
Section titled “S-FEED-2: Filter by event type”GIVEN user A sends GET /recommendations?type=EVENTTHEN the response contains only items with type EVENTAND items are ordered by personalized recommendation scoreS-FEED-3: Filter by gig type
Section titled “S-FEED-3: Filter by gig type”GIVEN user A sends GET /recommendations?type=GIGTHEN the response contains only items with type GIGS-FEED-4: Pagination
Section titled “S-FEED-4: Pagination”GIVEN user A has 50 recommended itemsWHEN user A sends GET /recommendations?limit=10&offset=20THEN the response contains items 21-30AND meta.total is 50S-FEED-5: New user empty state
Section titled “S-FEED-5: New user empty state”GIVEN user A has no interactions and no interestsWHEN user A sends GET /recommendationsTHEN the response contains events sorted by popularity (interaction count) then recencyS-FEED-11: Featured loads sectioned recommendation surfaces
Section titled “S-FEED-11: Featured loads sectioned recommendation surfaces”GIVEN the authenticated user opens FeaturedWHEN the page loads recommendation dataTHEN the page renders Recommended, Popular, and Upcoming sectionsAND each section can be filtered by type without changing the underlying interim ranking modelS-FEED-12: Featured keyword search narrows recommendation sections
Section titled “S-FEED-12: Featured keyword search narrows recommendation sections”GIVEN the authenticated user is on FeaturedWHEN the user enters a keyword search queryTHEN Recommended, Popular, and Upcoming reload with the queryAND ranking, pagination, empty states, and error states remain scoped per sectionAND the search does not use semantic embeddingsS-FEED-6: Cache hit [WIP — deferred to custom model phase]
Section titled “S-FEED-6: Cache hit [WIP — deferred to custom model phase]”GIVEN user A's recommendations were computed within the cache TTLWHEN user A sends GET /recommendationsTHEN the response is served from cacheS-FEED-7: Cache invalidation on interaction [WIP — deferred to custom model phase]
Section titled “S-FEED-7: Cache invalidation on interaction [WIP — deferred to custom model phase]”GIVEN user A's recommendations are cachedWHEN user A records a new interactionTHEN the cache is invalidatedAND the next GET /recommendations recomputes the rankingTest Cases
Section titled “Test Cases”See test-cases/recommendations/feed.md for the full test case registry (TC-FEED-001 through TC-FEED-016), including automated Featured-section coverage and manual UI verification.