Feature Deep-Dive: Feed & Ranking
What it does
Curates a unified, ranked stream that mixes the user’s obsessions with platform momentum. The endpoint behind the HUD serves JSON with cursor pagination and micro-caching so refresh-happy readers don’t melt the server.
Why it matters
A news HUD without thoughtful ranking is just a faster inbox. By blending focus topics with popularity, we give readers serendipity without sacrificing relevance. Bail on ranking and you end up doomscrolling again.
Design
flowchart LR
Sources[(sources)] -->|join| Items[(items)] --> Rank[Score & blend] --> Cache[In-memory cache]
Rank --> JSON[(JSON payload)] --> HUD[Client]
Tech choices & trade-offs
| Option | Perf | Complexity | Cost | DX | Why we picked/not |
|---|---|---|---|---|---|
| Server calc (API) | High | Low | $ | Great | Chosen — simple, stateless |
| Client calc | Med | Med | $ | Good | Extra client work |
| DB-side ranking | Med | Med | $ | Fair | Harder to iterate |
Implementation walkthrough
The brains live in web/src/app/api/feed/route.ts. Highlights:
const focusBlend = mixRatio ?? 0.7;
const popBlend = 1 - focusBlend;
const finalScore = focusBlend * focusScore + popBlend * popularity;
- Input validation courtesy of zod ensures
limit,before, andmixRatiostay sane. - We opportunistically ping stale RSS sources by calling the
rss-fetchEdge Function whenlast_polled_atlags. - Results are cached per user for 30 seconds in
FEED_CACHE, which covers quick refreshes while new items land.
Smart bits (gotchas)
- Focus topics come from metadata computed during ingestion; we default to a lower focus score if nothing matches.
- Twitter popularity pulls from
tweetMetricsinsideitems.metadata, so we normalize engagement counts to the same scale as RSS popularity. - Cursor pagination uses
published_attimestamps; no offsets, so the feed stays stable even as new items insert at the top.
Testing
We like to cover extremes.
// Focus should move the needle more than popularity when mixRatio > 0.5
const highFocus = score({ focus: 0.9, popularity: 0.2, mixRatio: 0.7 });
const lowFocus = score({ focus: 0.2, popularity: 0.8, mixRatio: 0.7 });
expect(highFocus).toBeGreaterThan(lowFocus);
Integration-wise, we add synthetic items via Supabase SQL and ensure the endpoint returns them in descending order with a valid nextCursor.
Operational notes
- Watch
jobsfor repeated errors; if a source keeps missing, the feed will flatten. - Instrument cache hit/miss ratios when you scale beyond a single node.
What we’d do next
- Explore materialized views for ranking once the algorithm stabilizes.
- Layer in behavioral signals from
user_item_scoresto personalize beyond focus tags.