ADR-002: Framework — Next.js (App Router)
Status
Accepted
Context
We wanted a single codebase for the HUD UI, API endpoints, and auth wiring. The App Router in Next.js 15 gives us React Server Components, file-based routing, and first-class support for the Supabase SSR helpers we rely on (web/src/lib/supabase/server-client.ts).
Options considered
- Next.js 15 (App Router) — Modern React tooling, built-in API routes, Turbopack dev flow.
- Remix — Great data loading story, but fewer guardrails for co-locating API handlers and SSR.
- SvelteKit — Lean and fast, but the team is more fluent in React + TypeScript.
Decision
Ship with Next.js 15, App Router mode. Pages like web/src/app/hud/page.tsx stay server-rendered while client components handle interactivity. API routes (e.g., web/src/app/api/sources/route.ts) live beside UI code, keeping mutations close to the features they support.
Consequences
Upside
- Blazingly fast dev loop via Turbopack.
- Server Components let us stream authenticated shells before data fetches complete.
- Easy to share types between client and server.
Trade-offs
- App Router conventions are still evolving, so newcomers need a primer.
- We lean on Vercel defaults for deployment; self-hosting would take extra plumbing.