ADR-001: Framework Selection
Source: ADR-001-framework-nextjs.md
ADR-001: Framework Selection — Next.js App Router
Date: 2026-04-09
Status: Accepted
Deciders: Platform Engineering Lead, Frontend Lead
CODITECT Classification: Architecture Decision Record · A6
-----|-------|
| Next.js 15 (App Router) | Full-stack, RSC for server rendering, Route Handlers for API, single deploy |
| Remix | Similar full-stack story; smaller ecosystem; less RSC maturity |
| Separate SPA + Express API | Two deploy units; more ops overhead; no SSR without extra work |
| SvelteKit | Excellent SSR; smaller talent pool for regulated enterprise context |
Decision
Adopt Next.js 15 with the App Router as the application framework.
- Participant page and organizer page built as React Server Components (RSC) — HTML rendered at the edge/server, no JS bundle required for initial render
- Real-time heatmap island (
SlotGrid,RealtimeProvider) uses client components with'use client'— only the interactive island hydrates in the browser - All backend logic lives in Next.js Route Handlers under
/app/api/— no separate Express server needed - Single Docker image, single deploy target
Consequences
Positive:
- Fast participant page load without full SPA bundle — critical for external users on mobile
- Single repository, single deploy, single team owns the full stack
- RSC architecture allows server-side data fetching with zero waterfall for initial render
- Strong ecosystem: Vercel, Railway, Render all support Next.js natively with zero config
Negative:
- App Router RSC patterns (server vs. client component boundary) require team familiarity — onboarding cost for engineers new to Next.js 13+
- WebSocket support requires a custom server or upgrade handler — Next.js does not natively expose a persistent WS server in standard mode (mitigated by ADR-003)
- Caching behaviour in App Router can be unintuitive — team must understand
revalidate,no-store, and Route Handler cache semantics
Neutral:
- Next.js is maintained by Vercel; not a concern for v1.0 but monitor for licensing changes post-acquisition scenarios (see A13 Longevity Assessment)
Alternatives Rejected
Separate SPA + Express API: Two repos, two CI pipelines, two deploy targets, cross-origin CORS complexity — all unnecessary overhead for a tool this scope.
SvelteKit: Excellent technical choice but smaller talent pool makes hiring and onboarding harder in the enterprise context CODITECT operates in.
Remix: Comparable to Next.js but App Router RSC is more mature for server-first rendering as of 2026. Next.js has wider adoption giving more Stack Overflow / community answers.
Review Trigger
Revisit if Next.js introduces breaking App Router changes in a major version, or if WebSocket server integration becomes incompatible with Next.js custom server model (per ADR-003).