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,56 @@
+# Logical Components — Unit 1: Project Scaffold & Infrastructure
+
+## Component Overview
+The frontend scaffold is composed of the following logical components that realize the NFR design patterns.
+
+## Mermaid Diagram — Component Interaction (colored by layer)
+
+```mermaid
+graph TD
+    Root[Root App] --> Router[TanStack Router]
+    Router --> AuthLayout[Auth Layout]
+    Router --> PublicRoutes[Public Routes]
+    AuthLayout --> Dash[Dashboard]
+    AuthLayout --> Users[Users]
+    AuthLayout --> Cms[CMS Mgmt]
+
+    Root --> I18n[i18next Provider]
+    Root --> Toast[Toast Provider]
+    Root --> Api[ApiClient]
+
+    Api --> MSW[MSW Handlers]
+    Api --> AuthCtx[AuthContext]
+
+    classDef root fill:#e9d5ff,stroke:#6b21a8,stroke-width:2px,color:#6b21a8;
+    classDef provider fill:#bae6fd,stroke:#0369a1,stroke-width:2px,color:#0369a1;
+    classDef client fill:#fed7aa,stroke:#c2410c,stroke-width:2px,color:#c2410c;
+    classDef route fill:#c6f6d5,stroke:#22543d,stroke-width:2px,color:#22543d;
+
+    class Root root;
+    class I18n,Toast,AuthCtx provider;
+    class Api,MSW client;
+    class Router,AuthLayout,PublicRoutes,Dash,Users,Cms route;
+```
+
+Text alternative: Root bootstraps providers (i18n, toast, auth) and TanStack Router; authenticated routes live under a layout protected by AuthContext; API client is shared and uses MSW in tests.
+
+## Key Logical Components
+
+| Component | Responsibility | NFR / BR Link |
+|-----------|----------------|---------------|
+| `ApiClient` | fetch wrapper with credentials, throws `ProblemDetailsError` | BR-U1-03, BR-U1-04, NFR-U1-05 (error mapping) |
+| `AuthContext` | in-memory token + user state, silent refresh on mount | BR-U1-01, BR-U1-02 |
+| `I18nProvider` | react-i18next + detector + lazy locale loader | NFR-U1-05, Q4-B |
+| `ToastProvider` | shadcn/ui toast primitive exposed via `useToast()` | NFR-U1-03, Q5-B |
+| `MSW Handlers` | feature-scoped mock handlers under `src/mocks/` | NFR-U1-04, Q3-B |
+| `Route Modules` | lazy-loaded per-feature route files | NFR-U1-01, Q1-A |
+| `FocusTrap` | radix/shadcn dialog primitive for modals only | NFR-U1-02, Q2-A |
+| `vite-env.d.ts` | typed `import.meta.env` + optional Zod config hook | NFR-U1-07, Q6-A |
+
+## Integration Points
+- All authenticated pages receive `AuthContext` via layout.
+- Language switcher lives in the top-right user menu and updates both i18next and persisted preference.
+- Error toasts are triggered from within pages or forms; 401 errors bubble to `AuthContext.logout()`.
+- Tests import handlers from `src/mocks/index` and wrap the component tree with all providers.
+
+These components form a minimal, maintainable foundation that satisfies all NFR-U1 requirements without introducing heavy dependencies.
@@ -0,0 +1,69 @@
+# NFR Design Patterns — Unit 1: Project Scaffold & Infrastructure
+
+## 1. Performance — Route-Based Code Splitting (Answer Q1-A)
+**Pattern**: Per-feature route modules with lazy-loaded layouts and page components.
+
+- TanStack Router `createLazyFileRoute` for dashboard, users, cms routes
+- Auth and root shell remain eager for fast initial paint and login
+- Vite automatically emits separate chunks per lazy route
+- Aligns with NFR-U1-01 (smallest possible bundle) and BR-U1-05 (TanStack Router)
+
+## 2. Accessibility — Keyboard & Focus Trap (Answer Q2-A)
+**Pattern**: Browser-native Tab order + shadcn/ui focus-visible + modal focus trap only.
+
+- All interactive elements use native `<button>`, `<a>`, form controls
+- `focus-visible` ring provided by shadcn/ui theme (Tailwind ring-2 ring-offset-2)
+- `FocusTrap` component (from `@radix-ui/react-focus-trap` or shadcn/ui dialog primitive) applied exclusively to modals and confirmation dialogs
+- No custom roving tabindex or arrow-key navigation unless explicitly required later
+
+## 3. Testing — Feature-Scoped MSW Handlers (Answer Q3-B)
+**Pattern**: Feature folders under `src/mocks/` with barrel exports.
+
+```
+src/mocks/
+  auth/
+    handlers.ts
+    fixtures.ts
+  users/
+    handlers.ts
+  index.ts
+```
+- `auth/handlers.ts` exports `authHandlers` array used in login, refresh, 401-retry tests
+- Easy to extend per future feature without central file bloat
+- Supports NFR-U1-04 (>70% coverage on auth components)
+
+## 4. Internationalization — Lazy Language Loading (Answer Q4-B)
+**Pattern**: Dynamic import of active locale only.
+
+- `i18next` initialized with `react-i18next` and `i18next-browser-languagedetector`
+- On language change: `i18next.changeLanguage(lng)` triggers `import(`../../public/locales/${lng}/translation.json`)`
+- Fallback to English; no eager bundling of both languages
+- Language switcher in user menu triggers the dynamic load + persists choice in localStorage via detector
+
+## 5. Error Handling — Per-Component ProblemDetails Mapping (Answer Q5-B)
+**Pattern**: Context-aware error presentation instead of global interceptor.
+
+- `ApiClient` throws typed `ProblemDetailsError` (extends Error)
+- Each page/form catches and decides:
+  - 401/403 → redirect or global AuthContext logout
+  - Validation errors (400) → inline field errors via react-hook-form
+  - Transient errors → shadcn/ui toast via `useToast()`
+- Keeps UI responsive and avoids one-size-fits-all toasts
+
+## 6. Configuration — Typed Vite Env + Optional Zod (Answer Q6-A)
+**Pattern**: Strong typing in `vite-env.d.ts` + runtime validation hook.
+
+```ts
+// vite-env.d.ts
+interface ImportMetaEnv {
+  readonly VITE_API_BASE_URL: string;
+  // future flags...
+}
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}
+```
+- Optional `useAppConfig()` hook runs Zod parse once at bootstrap (development warning only)
+- Production trusts `.env` values (no runtime overhead)
+
+All patterns respect the "minimal viable" constraints from NFR Requirements (no Sentry, no pre-commit, basic a11y).