PersonalBlog/docs/adr/ADR-008-react-vite-admin.md

ADR-008: React/Vite admin

• Status: Accepted
• Date: 2026-08-31
• Deciders: platform stream
• References: ADR index (section 70, docs/adr/README.md), ADR-001, ADR-007, Architecture wiki (sections 1, 4, 9, 11, 20, 42), Technology-Stack wiki (sections 5.2, 5.3, 6, 7, 8)

Context

EPPP is a modular monolith (ADR-001) whose single application image contains the public server, admin API, rendering pipeline, extension runtime, core services, built admin assets and first-party extensions (Architecture §4). The v0.1 scope explicitly includes an "administration interface" (§1), and Architecture §20 already fixes its shape: a React client app built with Vite, served by the same image, with /admin/* talking to the admin API under /api/admin/v1/* and an initial IA of Dashboard, Content→Posts, Home, Navigation, Appearance (active theme, theme settings), Extensions and Settings→Site. ADR-001 fixes the runtime as "Node.js 24 LTS with Fastify 5, PostgreSQL 18, React 19 for server-rendered public components and a Vite admin".

React and Vite are already the pinned toolchain in the golden compatibility tuple. React / React DOM 19.2.8 (class C, exact-pinned) is in the runtime stack and golden tuple (Technology-Stack §5.2, §7), and the build/admin/test toolchain is pinned to Vite 8.2.2, @vitejs/plugin-react 6.1.0, pnpm 11.23.0, Vitest 4.1.10 and Playwright 1.62.1 (§5.3). The LTS strategy keeps React exact-pinned at 19.2.8, keeps React Server Components out of v1 and keeps React out of persisted content formats (§6); direct platform dependencies are exact-pinned with a committed lockfile (§8).

The workspace does not implement the admin app yet — apps/server is the bare Fastify health shell and there is no apps/admin (Architecture §9; the CI build-apps stage already globs apps/** so the admin is picked up when it lands). This ADR therefore records the decision ahead of the code that implements it, formalising what the Architecture and Technology-Stack wikis already mandate: the admin frontend is a React client app built with Vite and served by the same application image.

Decision

EPPP builds the admin frontend with React/Vite admin: a React client application built with Vite — React 19.2.8 and Vite 8.2.2, exact-pinned class C dependencies from the golden compatibility tuple (Technology-Stack §5.2, §5.3, §7) — served by the same application image (ADR-001, Architecture §4). The admin lives under /admin/* and calls the admin API at /api/admin/v1/* (§20, §42). It is deliberately a separate concern from the public rendering pipeline: public pages stay server-rendered with no client hydration (ADR-007, §19.1), while the admin is a client-rendered SPA — the interactive management surface where JavaScript is expected and required. React Server Components stay out of v1 and React stays out of persisted content formats (Technology-Stack §6). The decision text — React/Vite admin — matches the ADR index entry (ADR-008, section 70).

Alternatives

• Server-rendered admin through the public React SSR pipeline — rejected: the admin is an interactive management surface where JavaScript is expected; routing it through the zero-JavaScript, non-hydrated SSR pipeline (ADR-007, §19.1) would buy nothing — every admin page needs client interactivity — and would couple admin rendering to the public pipeline's per-request server rendering.
• Separate admin framework (e.g. Next.js, Angular, Vue SPA) — rejected: the golden tuple pins React 19.2.8 (Technology-Stack §5.2, §7) and ADR-001 already records "a Vite admin"; a second frontend ecosystem would split the admin UI from the public components with no v1 requirement justifying it.
• Framework-less Vite / hand-rolled DOM — rejected: the admin IA (§20) needs a component model for the content, theme, extension and settings screens; re-implementing state management and composition by hand duplicates what React already provides, and the golden tuple already pins React.
• Build-time static-site-generated admin — rejected: the admin is an authenticated, connection-backed interface over the canonical database (ADR-005, ADR-019); build-time HTML would go stale against the canonical DB and add a rebuild/redeploy cycle per content change.
• Admin as a separate service or image — rejected: ADR-001 fixes one application image containing built admin assets; a separate admin deployment would break the single-deployable-unit model and add service boundaries with no v1 benefit.

Consequences

• Positive: one frontend technology — React 19.2.8 — spans the public SSR pipeline (ADR-007) and the admin SPA, so patterns, components and the golden tuple pin are shared; Vite gives fast HMR during admin development and a static build that ships inside the same image (ADR-001); the admin is explicitly outside the public zero-JavaScript baseline (§19.1), so its interactivity does not conflict with the public surface; the exact-pinned toolchain (Vite 8.2.2, React 19.2.8, committed lockfile) keeps admin builds reproducible under the ADR-026 upgrade lanes.
• Negative: the admin ships client JavaScript and a client runtime to authenticated admin users; a client-side build step joins the CI pipeline (the build-apps stage globs apps/**) and brings its own test tooling (Vitest, Playwright — Technology-Stack §5.3, §7); two rendering paths — public SSR and admin SPA — must be maintained, and the client/server contract at /api/admin/v1/* must stay versioned; the admin is an authenticated security surface (opaque DB-backed sessions, ADR-019) that the security baseline must keep covering (CSRF, session handling, authz).
• Neutral: Vite is a build-time detail — what ships is static assets served behind /admin/* from the same image; the decision constrains the later client-side decisions (zero-JS public baseline and the client-island model, ADR-009 and ADR-010) to the public surface, not the admin.

Operational impact

• apps/admin builds with Vite into static assets that are served by the same application image behind /admin/* (Architecture §20); there is no separate admin service, container or deployment (ADR-001).
• /admin/* serves the SPA shell; the SPA reads and writes through the admin API at /api/admin/v1/* (§42), secured by the Fastify lifecycle and opaque DB-backed sessions (ADR-019).
• The admin build runs in the CI build-apps stage — the pnpm apps/** glob picks apps/admin up automatically when the app lands — and admin behaviour is covered by Vitest unit suites and Playwright e2e (Technology-Stack §5.3, §7).
• Admin traffic is authenticated and internal; the admin is not part of the public zero-JavaScript surface (§19.1) — client JavaScript is expected and required there — so no byte-budget applies to admin assets.
• The admin is not implemented yet — today rollback is reverting this documentation commit; once the admin lands, rollback is redeploying the previous image (built admin assets live inside the image, so there is no separate asset deploy to coordinate).

Revisit trigger

• Revisit when the admin grows a requirement the React/Vite SPA model cannot meet — for example a genuinely different client architecture or offline capability — with evidence per the architecture review gates (ADR index section 68).
• Revisit when the golden tuple moves React or Vite to a new major — an ADR-recorded upgrade program item (Technology-Stack §7/§8, ADR-026 lane) — or changes the React pin's support class.
• Revisit when the public client-side decisions (ADR-009, ADR-010) change the boundary between the public surface and the admin, or the admin API contract at /api/admin/v1/* needs a different shape.
• Revisit when the single-image model (ADR-001) changes such that built admin assets must be served or deployed separately.