Architecture (Explanation)
Think of the HUD as a newsroom pipeline: scrapers collect leads, editors score them, and the front page rotates with calm confidence. Here’s how the pieces fit.
System overview
flowchart TB
subgraph Browser
UI[HUD UI]
end
subgraph Web["Next.js App (App Router)"]
ApiSources[/api/sources/]
ApiFeed[/api/feed/]
ApiBookmarks[/api/bookmarks/]
ApiPrefs[/api/preferences/]
CronRss[/api/cron/rss/]
CronX[/api/cron/x/]
end
subgraph Supabase
DB[(Postgres + RLS)]
RssWorker[[rss-fetch]]
TwitterWorker[[twitter-fetch]]
end
UI -->|Add/remove sources| ApiSources
UI -->|Fetch feed| ApiFeed
UI -->|Bookmarks| ApiBookmarks
UI -->|Prefs| ApiPrefs
Web -->|Service role HTTP| RssWorker
Web -->|Service role HTTP| TwitterWorker
RssWorker -->|Upsert items/jobs| DB
TwitterWorker -->|Upsert items/jobs| DB
ApiFeed -->|RLS reads| DB
ApiSources -->|RLS writes| DB
CronRss --> RssWorker
CronX --> TwitterWorker
The dividing lines follow ADR-005: Vercel handles the interactive Next.js app, while Supabase owns data, auth, and edge ingestion.
Component tour
HUD UI (React)
The HUD is a composed set of React Server Components and client islands. web/src/components/hud/feed-stream.tsx streams stories and leans on Zustand slices (web/src/store/feed-store.ts) to coordinate auto-scroll state. Failure modes show up as toast notifications via web/src/store/toast-store.ts; we’d rather give readers a heads-up than silently drop a story.
Next.js API layer
Routes under web/src/app/api/* are our editorial desks. Each handler uses zod schemas, pulls the Supabase session via getSupabaseServerClient, and speaks JSON. Because the handlers are stateless and sit behind Vercel’s edge cache, we scale horizontally by default. When a feed request lands, the logic in api/feed/route.ts blends focus and popularity, opportunistically triggers stale RSS fetches, and returns curated payloads.
Supabase Edge Functions
supabase/functions/rss-fetch and twitter-fetch are the night shift: they fetch new content, hash titles (hashContent in both files), prune anything older than 30 days, and update the jobs table with success/failure logs. Each run is isolated, so rate-limit spikes on one source don’t stall the rest.
Postgres (Supabase)
Everything persists to the schema defined in supabase/migrations/0001_init.sql. We lean on indexes (items_published_at_idx, sources_status_idx, etc.) to keep queries snappy. Supabase Advisors alert us if a migration introduces missing policies or slow plans.
Data model
classDiagram
class profiles {
uuid id
text email
text display_name
text[] focus_tags
jsonb ai_settings
timestamptz created_at
timestamptz updated_at
}
class sources {
uuid id
uuid user_id
text type (rss|twitter)
text url
text handle
text display_name
timestamptz last_polled_at
text status
timestamptz created_at
timestamptz updated_at
}
class items {
uuid id
uuid source_id
text title
text summary
text url
timestamptz published_at
jsonb metadata
text[] focus_topics
text content_hash
timestamptz created_at
timestamptz updated_at
}
class user_item_scores {
uuid user_id
uuid item_id
numeric score
timestamptz seen_at
boolean dismissed
timestamptz created_at
timestamptz updated_at
}
class bookmarks {
uuid id
uuid user_id
uuid item_id
timestamptz bookmarked_at
timestamptz surfaced_at
timestamptz created_at
timestamptz updated_at
}
class jobs {
uuid id
uuid source_id
text status
int attempts
timestamptz scheduled_for
timestamptz last_run_at
text error
timestamptz created_at
timestamptz updated_at
}
profiles <|-- sources : user_id
sources <|-- items : source_id
items <|-- bookmarks : item_id
items <|-- user_item_scores : item_id
sources <|-- jobs : source_id
A quick narrative through the tables:
profilesholds per-user preferences and AI settings. When/api/preferencesupdates, it writes toprofiles.ai_settingsand mirrors topic tags infocus_tagsfor fast querying.sourcesstores RSS URLs or normalized handles. The unique constraints ((user_id, url)and(user_id, handle)) prevent duplicate subscriptions.itemsis the newsroom archive.metadatacarries structured extras like tweet metrics, Gemini summaries, and popularity hints.user_item_scorestracks how often a user sees or dismisses items—future territory for smarter ranking.bookmarkspowers the resurfacing shelf;surfaced_atprevents Groundhog Day repeats.jobsis our black box recorder for ingestion attempts. Every edge function call writes a row describing its status.
Security & privacy posture
- Auth & RLS — Supabase Auth handles identity; every table shown above has RLS enforcing
auth.uid(). Service-role keys only live on the server, never in the browser bundle. - Secrets — Gemini keys are saved per user inside
profiles.ai_settingsvia/api/ai/key. The route never echoes secrets back once stored. - Data minimization — We store email + optional display name, nothing more personal. Items carry only the content needed to render cards.
- Transport — All calls happen over HTTPS. Cron endpoints (
/api/cron/rssand/api/cron/x) demand theCRON_SECRETheader in staging/production.
Warning
docs/x_api_v2.txtincludes sample placeholders for X API credentials. Treat them as dummy values only; generate and rotate real keys if you deploy ingestion in the wild.