[1/2] Port frontend to Next.js 16 (App Router)

[Nickatak]

PR: Port frontend to Next.js 16 (App Router)

Branch: next-rewrite stacked on docs-rewrite (#734).
Retarget to develop once #734 lands.

---

Summary

Replaces the legacy frontend/ (Vite 5 + React 18 + TypeScript 4 + react-router-dom + SCSS + a parallel Tailwind migration) with a Next 16 (App Router) + React 19 + TypeScript 5 + Tailwind 3.4 surface. Behavior preserved; styling carried forward intact so PR2 can sweep Tailwind classes and SCSS into co-located CSS Modules in a clean, isolated diff.

This is PR1 of a 2-PR chain. PR2 is Tailwind/SCSS → CSS Modules.

Why this shape

• Stacked on docs-rewrite because the docs in Rewrite docs/ for future-state architecture #734 describe the target state we are building. Reviewer can read the spec alongside the code.
• Two commits (scaffold + port) rather than dozens of granular ones. Scaffold = the empty Next.js shell + Docker infra; port = all React/TS/test/asset content moving in.
• Tailwind preserved through the port (deferred to PR2) so visual surface does not move while the framework changes underneath.

Commits

#	Subject
1	Scaffold Next.js 16 frontend and split stage Docker
2	Port legacy frontend to Next.js App Router

What's in this PR

Stack

• Next.js 16 (App Router, default Turbopack for dev). Bumped from Next 15 in the docs to match create-next-app@latest output.
• React 19, TypeScript 5.
• Tailwind 3.4 (carried over). Theme + content paths in frontend/tailwind.config.ts. Removed in PR2.
• SCSS (carried over). Tokens at src/shared/styles/; component-paired files alongside their components.
• Vitest + jsdom + @testing-library + vite-plugin-svgr replacing Jest.
• @floating-ui/react replacing react-popper (legacy not React-19 compatible).
• next/font/local for the bundled Roboto family.

Architecture

• src/app/ is route shims only; src/features/<feature>/ owns real work; src/shared/ is cross-feature primitives.
• (with-nav) and (auth) route groups hold the two layout shapes.
• frontend/ARCHITECTURE_MAP.md documents layer rules, route-shim policy, controller-API policy, function-style convention, and a route-to-entry table.
• Each feature dir has a FEATURE_MAP.md (landing, credits, qualifier, session). privacy-policy and not-found are trivial enough to skip the map.

Routes after the port

Route	Entry
/	features/landing/components/LandingPage
/credits	features/credits/components/CreditsPage
/privacy-policy	features/privacy-policy/PrivacyPolicyPage
/qualifier/[page]	features/qualifier/components/QualifierConsole
/login	features/session/components/LoginForm
/signup	features/session/components/SignupForm
404	features/not-found/NotFoundPage

Notable per-component changes

• Pruned: /demo, /demo-tailwind (legacy showcase, no longer needed), the tw-components/ ↔ components/ duplication (tw versions win where both existed), App.tsx, index.tsx, Router.tsx (Next App Router replaces them).
• IconButton: iconUrl: string → Icon: ComponentType<SVGProps> so the SVGR-imported component can be passed directly.
• TextField: now generic over a react-hook-form value schema; legacy version was pinned to { password: string } and broke at type level for any non-password field.
• Dropdown: react-popper → @floating-ui/react. Outside-click handling moves into useDismiss; removes ~25 lines of manual document.body event wiring.
• TransitionWrapper: react-transition-group → mount/unmount. Visual fade is intentionally absent until PR2 reintroduces it via CSS Modules.
• CookieBanner: cookie read deferred to useEffect after a mount-then-render gate so server and client trees match (legacy ran the read at state init, which produced a hydration mismatch on any cookied visit).
• QualifiersContext: hydrates from localStorage via useEffect, not at state init — SSR can't read localStorage.
• Logo + credits illustration: SVGR-rendered SVGs need explicit h-{N} or h-auto to override their baked-in width/height attributes; CSS percentage widths alone don't propagate to height the way <img> does.
• /privacypolicy → /privacy-policy (hyphenated; standard URL casing).

SVG handling

• @svgr/webpack configured in next.config.ts for both Webpack and Turbopack with svgo: false so SVGO's default cleanupIds doesn't break clip-path id references in the logo files.
• Vite-style ?react/?url query suffixes are gone. Where the legacy used ?url for CSS background images (privacy-policy bg, landing page bg), the SVG file moved to public/svgs/ and is referenced as a path string — SVG-as-React-component cannot be used inside url(...).

Dev infra

• dev/vite.Dockerfile → dev/next.dockerfile.
• docker-compose.yml: vite service → next service, port 5175 → 3000, develop.watch cleaned to ignore node_modules/ and .next/.
• Docs (README.md, docs/developer/design-system.md) bumped Next.js 15 → 16.

Stage infra (folded in)

• stage/Dockerfile (combined image that baked the Vite build into Django) split into stage/next.dockerfile + stage/django.dockerfile.
• docker-compose.stage.yml runs three services: pgdb (5433:5432), django (8000), next (3000), with BACKEND_INTERNAL_URL=http://django:8000 driving Next's /api/* and /admin/* rewrites so the local stage matches the deployed stage's single-origin shape.
• .github/workflows/build-deploy-stage.yml and aws/task-definition.json deleted — the deploy pipeline lives in hackforla/incubator now.

These were originally tagged as post-merge cleanup in #734 but are pulled forward here to keep dev → stage → deploy on the same image shape.

Misc

• .gitignore rules data and media are now /data and /media. The unanchored versions matched any directory named data/media anywhere, which would silently hide the new per-feature data/ directories that the port introduces.

What's deferred

• Tailwind classes + carry-over SCSS → CSS Modules (PR2 in this chain).
• Disable GitHub Pages (post-merge, repo settings).
• .github/workflows/lint.yml + delete legacy linter.yml (post-merge cleanup).
• jest-react-test.yml workflow rename (still labeled "Jest" but runs Vitest now — functional but stale).
• NEXT_PUBLIC_API_URL in dev/dev.env is cross-origin; with the rewrite-based stage shape, dev should probably use the same relative-URL pattern. Not addressed here.
• SCSS deprecation warning in _NotFoundPage.scss (breakpoint-media-max("smtablet") style is deprecated). Pre-existing; warns but compiles.
• TextField and LandingPage test rewrites (describe.skip with inline notes — the underlying components changed shape during the port).

Test plan

• cd frontend && npm install — lockfile is committed; deps install clean.
• npm run build — production build succeeds, all 7 routes compile.
• docker compose up — pgdb, django, next services come up; frontend on localhost:3000.
• Walk the site:
  • / renders landing hero, mission section, CoP cards
  • Click a CoP card → dialog opens with that CoP's detail (X top-right, nav on left, content on right)
  • Footer "Donate" button opens hackforla.org/donate in a new tab
  • /credits toggles between Illustrations and Iconography; high-five illustration sized correctly
  • /privacy-policy renders with the bg-top illustration on lg screens
  • /login renders the form with side illustration; bad email shows validation error
  • /signup renders four fields + form-level validation
  • /qualifier/1 shows CoP cards; selecting one enables Continue
  • /qualifier/2 shows skill matrix; back/forward through skill batches works
  • /qualifier/3 shows weekly availability calendar; timezone dropdown opens and selects
  • /foo (any unknown URL) shows the 404 with HeaderNav + FooterNav
  • Cookie banner appears on first visit, dismisses, stays dismissed across reload (no hydration warning in console)
• npm test — 12 tests pass, 2 skipped (TextField, LandingPage with WHY notes).
• docker compose -f docker-compose.stage.yml up — pgdb (5433), django (8000), next (3000) come up; /api/* and /admin/* from localhost:3000 proxy to django via Next rewrites. Not yet smoke-tested.

Stacking note

This PR is stacked on docs-rewrite (PR #734). When #734 lands, retarget this PR's base to develop and rebase. Squash-merge into develop is fine; the per-commit split (scaffold + port) is preserved here on the branch but does not need to land on develop as separate commits.

[RSkuma]

Discussed and approved