Functional design, NFR requirements, code generation plan and summary, and build-and-test instructions with results. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
6.1 KiB
6.1 KiB
Tech Stack Decisions — frontend-shell
Existing stack (unchanged): React 19, TypeScript, Vite, TanStack Router, Chakra UI v3, pnpm. See technology-stack.md.
All new packages are installed with pnpm at their latest stable version and pinned by pnpm-lock.yaml (SECURITY-10).
Dependency Changes
| Package | Change | Kind | Why |
|---|---|---|---|
vitest |
add | dev | Test runner, native to Vite (NFR-03) |
@vitest/coverage-v8 |
add | dev | Coverage with per-file thresholds (NFR-M-02) |
jsdom |
add | dev | DOM environment for component tests |
@testing-library/react, @testing-library/user-event, @testing-library/jest-dom |
add | dev | Component tests from the user's perspective |
fast-check |
add | dev | Property-based testing (PBT-09) |
vitest-axe (on axe-core) |
add | dev | Accessibility assertions in component tests (Q4 = A) |
eslint, @eslint/js, typescript-eslint, eslint-plugin-react-hooks, eslint-plugin-jsx-a11y, globals |
add | dev | Linting (Q5 = A) |
@lhci/cli |
add | dev | Lighthouse CI with assertions (Q3 = B) |
next-themes |
remove | — | The site is fixed to light; it only added an inline script (Q2 = A) |
@vitejs/plugin-react |
move to dev | dev | Build tool (FR-11) |
@tanstack/react-router-devtools |
move to dev | dev | Loaded only in development (NFR-P-04) |
Decisions
TD-01 Property-based testing: fast-check (PBT-09)
- Generators: fast-check provides custom arbitraries for the domain types (
SocialLink,EmailAddress,SitePage, paths, JSON values). - Shrinking and replay: shrinking is on by default. On failure, fast-check reports the seed and path, and
fc.assert(..., { seed, path })replays the exact case. - Test runner: runs as normal Vitest tests, so no separate runner is needed.
- Default runs: 100 per property. Raise it per property only when needed.
- Considered:
@fast-check/vitest(addstest.prop). Not needed: plainfc.assertinsideitis enough and is one dependency less.
TD-02 Test environment: Vitest + jsdom
- The Vitest config lives in
vite.config.ts(testsection), so tests use the same aliases and plugins as the app. - Setup file:
@testing-library/jest-dommatchers +vitest-axematchers. - Router-dependent components are tested inside a memory-history router.
- Fallback: if
vitest-axeturns out to be incompatible with the installed Vitest version, a ~10-line customtoHaveNoViolationsmatcher onaxe-corereplaces it. Same assertion, one dependency less.
TD-03 Linting: ESLint flat config
- Rule sets:
@eslint/jsrecommended,typescript-eslintrecommended,react-hooksrecommended,jsx-a11yrecommended. - Prettier remains the formatter. No stylistic ESLint rules, to avoid conflicts.
- Excluded:
routeTree.gen.tsanddist.
TD-04 Lighthouse CI
- Server:
@lhci/clistartspnpm preview, so the real production headers and the SPA fallback apply. It measures every route insitePagesplus one unknown URL (the 404), on both mobile and desktop. - Assertions:
- Performance ≥ 0.9
- Accessibility = 1
- Best Practices = 1
- SEO = 1 on indexed URLs. On
noindexURLs only theis-crawlableaudit is allowed to fail (NFR-S-02).
- Requirements: a local Chrome/Chromium.
- Results: written to
.lighthouseci/, which is git-ignored. No upload to a public server. - Scripts:
pnpm lighthouseruns it on its own.- It is part of
pnpm check(CQ1 = A).
TD-05 Security headers in Vite
- One source:
securityHeaders(mode)in a small config module, used byserver.headers(dev) andpreview.headers.- Production mode returns the strict set (NFR-SEC-01/02).
- Dev mode adds only the Vite exceptions (NFR-SEC-03).
- Testing: the function is pure, so a test can check that the production CSP never contains
unsafe-eval, never containsunsafe-inlineinscript-src, and never containsws:. - Production: the same production set is the required configuration for the future host.
TD-06 Vite config in TypeScript
vite.config.jsbecomesvite.config.ts. It contains:- the existing plugins
- the local
sitemapplugin (BR-SEO-06), which readssitePages - the security headers (TD-05)
- the Vitest
testsection
- Plugin: about 30 lines, using Rollup's
generateBundlehook to emitsitemap.xml. The XML itself comes from the pure, testedsitemapXml.
TD-07 Scripts in package.json
| Script | Runs |
|---|---|
test |
vitest run --coverage |
test:watch |
vitest |
lint |
eslint . |
format:check |
prettier --check . |
audit:deps |
pnpm audit --audit-level high |
lighthouse |
lhci autorun |
check |
lint → format:check → test → build → audit:deps → lighthouse, stopping at the first failure |
TD-08 Colour mode
- Without
next-themes: the light theme is the default. The_darksemantic token values stay in the theme, so a dark mode can be added later without rework. - Considered: keeping
next-themesand allowing its script via a CSP hash. Rejected: the hash breaks on every library update, and the script has no use while the site is light-only.
Security Baseline Compliance (NFR Requirements)
| Rule | Status | Rationale |
|---|---|---|
| SECURITY-04 | Compliant | Header set + CSP defined, unsafe-inline only for styles with documented justification (NFR-SEC-01…04) |
| SECURITY-09 | Compliant | Devtools dev-only, starter assets removed, generic error pages |
| SECURITY-10 | Compliant | Lock file, audit:deps in check, unused next-themes removed, build tools in dev |
| SECURITY-13 | Compliant | No CDN resources; Lighthouse CI uploads nothing externally |
| SECURITY-15 | Compliant | Root error boundary (NFR-R-01) |
| SECURITY-03, -14 | N/A | No server component; revisit with the .NET API |
| Others | N/A | As in requirements.md |
PBT Compliance (NFR Requirements)
| Rule | Status | Rationale |
|---|---|---|
| PBT-09 | Compliant | fast-check: custom arbitraries, shrinking, seed replay, runs in Vitest (TD-01) |
| Others | N/A at this stage | Applied in Code Generation |