Recommendation Feed
Overview
Section titled “Overview”The recommendation feed is the primary discovery surface. It presents a blended list of events and gigs ranked by the recommendation model (currently interim heuristic ranking — see model.md). Users can filter by type.
Endpoint
Section titled “Endpoint”GET /recommendations returns the personalized feed.
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) |
Response
Section titled “Response”Returns a paginated response shaped as { items, meta }, where items is an array of Event objects ranked by recommendation score. The meta object includes total, limit, 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).
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-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 ranking