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

OptionPerfComplexityCostDXWhy we picked/not
Server calc (API)HighLow$GreatChosen — simple, stateless
Client calcMedMed$GoodExtra client work
DB-side rankingMedMed$FairHarder 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, and mixRatio stay sane.
  • We opportunistically ping stale RSS sources by calling the rss-fetch Edge Function when last_polled_at lags.
  • 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 tweetMetrics inside items.metadata, so we normalize engagement counts to the same scale as RSS popularity.
  • Cursor pagination uses published_at timestamps; 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 jobs for 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_scores to personalize beyond focus tags.