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.
  • Next config: web/next.config.ts
  • API entry point: web/src/app/api/feed/route.ts
  • Related ADRs: ADR-004, ADR-005