Glossary

Reader-friendly definitions with direct tie-ins to the HUD. Skim it once, then use it as reference when jargon sneaks into code reviews.

  • Smoke test
    • Quick check that core paths work (build, basic routes).
    • How we use it: CI runs a build and simple route checks.
  • Refactor
    • Change code structure without changing behavior.
    • How we use it: clarify API handlers and stores between releases.
  • Idempotent
    • Multiple identical requests produce the same result.
    • How we use it: bookmark insert guarded by unique key.
  • Eventual consistency
    • Data converges to a correct state over time.
    • How we use it: ingestion may lag; HUD catches up on refresh.
  • Circuit breaker
    • Stop calling a failing dependency temporarily.
    • How we use it: consider for X API rate-limit storms.
  • Backpressure
    • Slow down producers when consumers can’t keep up.
    • How we use it: throttle ingestion; cache feed responses.
  • Rate limiting
    • Cap requests per unit time.
    • How we use it: respect X API, cron cadence.
  • Blue/green deploy
    • Two production stacks; switch traffic to the new one.
    • How we use it: conceptually similar to Vercel promote/rollback.
  • Canary
    • Release to a small subset first.
    • How we use it: try on preview deployments before prod.
  • Observability
    • Telemetry to understand system behavior.
    • How we use it: jobs log + function logs + Vercel logs.
  • SLA/SLO/SLI
    • Agreement/objective/indicator for reliability.
    • How we use it: target P95 feed < 100 ms in production.
  • RLS (Row Level Security)
    • Postgres policy to restrict rows per user.
    • How we use it: all user tables enforce auth.uid().
  • Edge Function
    • Serverless function running near the DB.
    • How we use it: RSS/X ingestion workers.
  • Service role
    • Supabase key with full access.
    • How we use it: server-only writes to tables.
  • Cursor pagination
    • Use a position token (timestamp) instead of offsets.
    • How we use it: before ISO date for /api/feed.
  • Focus score
    • Degree an item matches user’s topics.
    • How we use it: weight in ranking formula.
  • Popularity score
    • Platform engagement proxy normalized to 0–1.
    • How we use it: blend with focus for final rank.
  • Deduplication hash
    • Content-based fingerprint to avoid duplicates.
    • How we use it: content_hash per item.
  • Retention policy
    • Time/size-based deletion of old data.
    • How we use it: 30 days and ~300 items/source.
  • Turbopack
    • Rust-based Next.js dev bundler.
    • How we use it: fast dev server for better DX.
  • Zod
    • Type-safe validation library.
    • How we use it: validate API bodies/queries.
  • Zustand
    • Minimal state manager for React.
    • How we use it: store slices for HUD state.
  • App Router
    • Next.js routing with server components.
    • How we use it: web/src/app/* structure.
  • Cron
    • Scheduled execution pattern.
    • How we use it: Vercel Cron triggers ingestion.
  • ADR (Architecture Decision Record)
    • Documented decision with trade-offs.
    • How we use it: link choices throughout this book.