QQuiz/docs/audit/frontend-migration.md

Frontend Migration Plan

Decision

The legacy Vite SPA remains in frontend/ as a fallback.

The new frontend is being built in web/ with:

• Next.js App Router
• TypeScript
• Tailwind CSS
• shadcn/ui component model

The abandoned ESA captcha integration has been removed from the legacy login page.

Why a Rewrite Instead of an In-Place Port

The legacy frontend mixes too many browser-only assumptions into core runtime boundaries:

• token storage in localStorage
• window.location redirects inside transport code
• client-only route protection
• SSE token passing in query strings

Those patterns do not map cleanly onto Next App Router and server-first auth.

New Runtime Model

Auth

• Login goes through Next route handlers
• Backend JWT is stored in an HttpOnly cookie
• Browser code never reads the raw token

Data

• Server pages use server-side fetch helpers
• Client mutations use browser-side fetch helpers against Next proxy routes
• URL state is used for pagination and filters

Streaming

• Browser connects to a same-origin Next progress route
• The route reads the session cookie and proxies backend SSE
• Backend URL tokens are hidden from the browser

Directory Map

web/
  src/app/
  src/components/
  src/lib/
  src/middleware.ts

Migration Order

1. Auth shell, layouts, middleware, and proxy routes
2. Dashboard, exams list, questions list, and admin overview
3. Exam detail upload and progress streaming
4. Quiz and mistake-practice flows
5. Cutover, smoke testing, and legacy frontend retirement

Non-Goals for This First Slice

• No immediate removal of the legacy frontend/
• No backend contract rewrite yet
• No server actions as the primary data mutation layer