Preface

Grab a mug, flick the HUD into “drift,” and let’s talk shop. This field guide is written for builders who like their news curated and their architecture justified. If you can run npm run dev without looking it up, you’re in the right newsroom.

Who this is for

Anyone who has ever rage-closed a tab forest of RSS feeds or doom-scrolled X until the firehose drowned the signal. We built the HUD for developer/designers who want to steer their information diet, not fight it.

Why the HUD exists

Our own feeds were loud and jittery. So we stitched together a pipeline where Supabase Edge Functions sweep RSS and X profiles, Next.js APIs remix the data, and a Zustand-powered HUD nudges the best stories forward. The ranking math lives in code you can trace: peek at web/src/app/api/feed/route.ts and you’ll see the 70/30 focus-to-popularity blend we argue about in stand-up.

How to read this in 10 minutes

  1. Start with the Quickstart — run the HUD, run the smoke test, feel the loop.
  2. Skim the Project Snapshot — that table is your stack cheat sheet with ADR receipts.
  3. Dive into Architecture when you wonder “why pick Supabase over pg_cron?”; each choice links to a decision log.
  4. Keep the How-to recipes open for daily tasks like “spin up a cron job” or “roll back Vercel in 90 seconds.”
  5. Bookmark the Reference pages for those nights you need the exact query parameters.

Tip Every spicy opinion (looking at you, Vercel Cron) points to an ADR. We keep receipts so future-you can accept or refactor the call.