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:
beforeISO 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_hashper 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.