Project Snapshot (At-a-glance)

Here’s the cheat sheet we keep on the wall—what we run, why we run it, and which ADR backs the call.

Stack summary

LayerChoiceWhy we bet on itAlternativesStatus
RuntimeNode 20+Stable LTS, great perf profile, unlocks Rollup 4 + TurbopackDeno, BunAdopted
FrameworkNext.js 15 (App Router)Server + client in one repo, RSC where it helps, API routes co-locatedRemix, SvelteKitAdopted
UIReact 19 + Tailwind v4Minimal tokens, component ergonomics, works well with app/ slotsVanilla CSS, ChakraAdopted
StateZustandTiny API, selector-friendly, matches web/src/store/* slicesRedux Toolkit, ContextAdopted
DBSupabase Postgres 16Managed Postgres + RLS + advisors; see supabase/migrations/0001_init.sqlMySQL, SQLiteAdopted
AuthSupabase Auth (magic)One-click magic links, great DX, zero custom OAuth early onNextAuth, custom JWTAdopted
IngestionSupabase Edge FunctionsServerless scripts adjacent to DB, easy deploy via CLINext API, CloudflareAdopted
SchedulingVercel CronHosted, secret header support, pairs with our API triggersGitHub Actions, pg_cronAdopted
HostingVercel + SupabaseSplit brain: web on Vercel, data/edge on Supabase (see ADR-005)Fly.io, self-hostAdopted
AI SummariesGemini 1.5 FlashFast, affordable TL;DRs; fallback to user-provided keys (see ADR-007)OpenAI, ClaudeAdopted

Cross-refs: ADR-002 · ADR-001 · ADR-003 · ADR-004 · ADR-006.

Environments we care about

  • Local dev — npm run dev fires up Turbopack and the HUD. Pair it with npm run dev inside astro-book/ if you like previewing docs alongside code.
  • Preview — Every PR gets a Vercel Preview URL. We sanity-check /hud, /api/feed, and any UI polish here.
  • Production — Vercel production for the Next.js app; Supabase prod instance for Postgres + Edge Functions (with RLS turned to 11).

Deployment targets

  • Web app → Vercel build pipeline. Scripts live in web/package.json.
  • Edge workers → Supabase Functions: rss-fetch and twitter-fetch under supabase/functions/.

Non-negotiable constraints

  • Rate limits — Twitter’s v2 API is stingy. The worker at supabase/functions/twitter-fetch/index.ts respects retry headers and logs incidents into jobs.
  • RLS everywhere — Every table in supabase/migrations/0001_init.sql is locked to auth.uid(). Anything that needs cross-user access must use the service role.
  • Lean database — 30-day retention + 300 items per source keep Postgres nimble; pruning logic sits near the bottom of each ingestion function.