Adds nfr requirements and design for unit 1

2026-06-19 21:34:20 +02:00
parent 7e4397af4e
commit efd1569c26
6 changed files with 314 additions and 8 deletions
@@ -0,0 +1,40 @@
+# NFR Requirements — Unit 1: Project Scaffold & Infrastructure
+
+## NFR-U1-01: Performance — Bundle Size
+- Target: Keep initial JS bundle (gzipped) as small as possible
+- Vite must be configured for aggressive tree-shaking and code-splitting via TanStack Router file-based routes
+- No hard numeric budget; continuous monitoring via `vite build --analyze` recommended in CI later
+- See BR-U1-01, BR-U1-05 for lazy loading expectations
+
+## NFR-U1-02: Accessibility — Keyboard & Focus (A11Y)
+- Minimum requirement: Basic keyboard navigation and visible focus indicators on all interactive elements
+- All form controls, buttons, and links must be reachable via Tab and operable with Enter/Space
+- No full WCAG 2.2 AA/AAA compliance required for v1 (internal admin tool)
+- shadcn/ui components must expose proper ARIA attributes by default
+
+## NFR-U1-03: Observability — Client-side Error Reporting
+- No external error monitoring (Sentry, OpenTelemetry) in initial scaffold
+- Errors are logged to console + shown via user-friendly toast/banner (using existing shadcn/ui toast primitives)
+- Future extension point: add observability library later without changing API client contract
+
+## NFR-U1-04: Testing — Component & Integration Tests
+- Vitest + React Testing Library + MSW MUST be included in the scaffold
+- Example tests required for: login form submission, 401-intercept + retry flow, and authenticated route guard
+- Tests must run with `pnpm test` and achieve >70% coverage on auth-related components
+- MSW handlers must mock the real backend endpoints (`/api/v1/auth/*`)
+
+## NFR-U1-05: Internationalization — i18n
+- react-i18next + i18next-browser-languagedetector MUST be added
+- Supported languages in v1: English (default) + Dutch
+- Language switcher component must be present in the top bar / user menu
+- All user-facing strings in the scaffold (login, dashboard shell, error messages) must be wrapped in `t()` calls
+- Translation files: `public/locales/en/*.json` and `public/locales/nl/*.json`
+
+## NFR-U1-06: Maintainability — Pre-commit Hooks
+- No husky + lint-staged in the initial scaffold
+- Rely on editor integration (ESLint/Prettier on save) and CI pipeline only
+- Pre-commit enforcement can be added in a later NFR iteration if desired
+
+## NFR-U1-07: Maintainability — Configuration
+- All environment-specific values (API base URL, feature flags) stored in `.env` / `.env.example` following Vite conventions
+- No magic strings for route paths or API endpoints — use constants / TanStack Router file naming
@@ -0,0 +1,67 @@
+# Tech Stack Decisions — Unit 1: Project Scaffold & Infrastructure
+
+## Existing Stack (from ZIP example + requirements)
+All prior choices retained:
+- **Vite 6** — Build tool
+- **React 18** — UI library
+- **TypeScript 5** — Type safety
+- **TanStack Router v1** — File-based routing (replaces React Router)
+- **Tailwind CSS v4** + **shadcn/ui** — Styling & components (primary color `#ac0000`)
+- **pnpm** — Package manager
+- **ESLint + Prettier** (4-space indent) — Formatting
+
+---
+
+## New: Testing Framework
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Test runner | Vitest | Native ESM, fast, Vite-native, excellent TypeScript support |
+| Component testing | React Testing Library | Industry standard for React; focuses on user behavior |
+| API mocking | MSW (Mock Service Worker) | Works in browser + Node; realistic network layer for auth flows |
+| Test command | `pnpm test` | Consistent with existing pnpm scripts |
+
+---
+
+## New: Internationalization
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| i18n library | react-i18next + i18next-browser-languagedetector | Most popular React i18n solution; automatic language detection |
+| Translation files | JSON under `public/locales/{en,nl}/` | Standard, easy to edit, works with Vite static assets |
+| Language switcher | Custom component in user menu | Keeps UI consistent with shadcn/ui |
+
+---
+
+## New: Environment Configuration
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Env variables | Vite `import.meta.env.VITE_*` | Official, type-safe, exposed to client |
+| Example file | `.env.example` (committed) | Documents required variables for new developers |
+| Local overrides | `.env.local` (gitignored) | Follows Vite + dotenv conventions |
+
+---
+
+## Explicitly NOT included (per answers)
+
+- No Sentry / OpenTelemetry in scaffold
+- No husky + lint-staged pre-commit hooks
+- No WCAG 2.2 AA/AAA a11y requirements beyond basic keyboard support
+- No hard bundle-size budget (optimize for smallest possible)
+
+---
+
+## appsettings / env additions (frontend only)
+
+`.env.example` (committed):
+```env
+VITE_API_BASE_URL=http://localhost:5000
+```
+
+`.env.local` (developer only, gitignored):
+```env
+VITE_API_BASE_URL=http://localhost:5000
+```
+
+No changes needed to backend `appsettings.json` for Unit 1.