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:

  • profiles holds per-user preferences and AI settings. When /api/preferences updates, it writes to profiles.ai_settings and mirrors topic tags in focus_tags for fast querying.
  • sources stores RSS URLs or normalized handles. The unique constraints ((user_id, url) and (user_id, handle)) prevent duplicate subscriptions.
  • items is the newsroom archive. metadata carries structured extras like tweet metrics, Gemini summaries, and popularity hints.
  • user_item_scores tracks how often a user sees or dismisses items—future territory for smarter ranking.
  • bookmarks powers the resurfacing shelf; surfaced_at prevents Groundhog Day repeats.
  • jobs is 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_settings via /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/rss and /api/cron/x) demand the CRON_SECRET header in staging/production.

Warning docs/x_api_v2.txt includes sample placeholders for X API credentials. Treat them as dummy values only; generate and rotate real keys if you deploy ingestion in the wild.