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
| Layer | Choice | Why we bet on it | Alternatives | Status |
|---|---|---|---|---|
| Runtime | Node 20+ | Stable LTS, great perf profile, unlocks Rollup 4 + Turbopack | Deno, Bun | Adopted |
| Framework | Next.js 15 (App Router) | Server + client in one repo, RSC where it helps, API routes co-located | Remix, SvelteKit | Adopted |
| UI | React 19 + Tailwind v4 | Minimal tokens, component ergonomics, works well with app/ slots | Vanilla CSS, Chakra | Adopted |
| State | Zustand | Tiny API, selector-friendly, matches web/src/store/* slices | Redux Toolkit, Context | Adopted |
| DB | Supabase Postgres 16 | Managed Postgres + RLS + advisors; see supabase/migrations/0001_init.sql | MySQL, SQLite | Adopted |
| Auth | Supabase Auth (magic) | One-click magic links, great DX, zero custom OAuth early on | NextAuth, custom JWT | Adopted |
| Ingestion | Supabase Edge Functions | Serverless scripts adjacent to DB, easy deploy via CLI | Next API, Cloudflare | Adopted |
| Scheduling | Vercel Cron | Hosted, secret header support, pairs with our API triggers | GitHub Actions, pg_cron | Adopted |
| Hosting | Vercel + Supabase | Split brain: web on Vercel, data/edge on Supabase (see ADR-005) | Fly.io, self-host | Adopted |
| AI Summaries | Gemini 1.5 Flash | Fast, affordable TL;DRs; fallback to user-provided keys (see ADR-007) | OpenAI, Claude | Adopted |
Cross-refs: ADR-002 · ADR-001 · ADR-003 · ADR-004 · ADR-006.
Environments we care about
- Local dev —
npm run devfires up Turbopack and the HUD. Pair it withnpm run devinsideastro-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-fetchandtwitter-fetchundersupabase/functions/.
Non-negotiable constraints
- Rate limits — Twitter’s v2 API is stingy. The worker at
supabase/functions/twitter-fetch/index.tsrespects retry headers and logs incidents intojobs. - RLS everywhere — Every table in
supabase/migrations/0001_init.sqlis locked toauth.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.