From efd1569c2614f7a0702c625675c0e9076b4788c1 Mon Sep 17 00:00:00 2001 From: Sluijsens Date: Fri, 19 Jun 2026 21:34:20 +0200 Subject: [PATCH] Adds nfr requirements and design for unit 1 --- .../plans/unit-1-nfr-design-plan.md | 74 +++++++++++++++++++ .../plans/unit-1-nfr-requirements-plan.md | 16 ++-- .../unit-1/nfr-design/logical-components.md | 56 ++++++++++++++ .../unit-1/nfr-design/nfr-design-patterns.md | 69 +++++++++++++++++ .../nfr-requirements/nfr-requirements.md | 40 ++++++++++ .../nfr-requirements/tech-stack-decisions.md | 67 +++++++++++++++++ 6 files changed, 314 insertions(+), 8 deletions(-) create mode 100644 aidlc-docs/features/cms-frontend/construction/plans/unit-1-nfr-design-plan.md create mode 100644 aidlc-docs/features/cms-frontend/construction/unit-1/nfr-design/logical-components.md create mode 100644 aidlc-docs/features/cms-frontend/construction/unit-1/nfr-design/nfr-design-patterns.md create mode 100644 aidlc-docs/features/cms-frontend/construction/unit-1/nfr-requirements/nfr-requirements.md create mode 100644 aidlc-docs/features/cms-frontend/construction/unit-1/nfr-requirements/tech-stack-decisions.md diff --git a/aidlc-docs/features/cms-frontend/construction/plans/unit-1-nfr-design-plan.md b/aidlc-docs/features/cms-frontend/construction/plans/unit-1-nfr-design-plan.md new file mode 100644 index 0000000..75782e1 --- /dev/null +++ b/aidlc-docs/features/cms-frontend/construction/plans/unit-1-nfr-design-plan.md @@ -0,0 +1,74 @@ +# NFR Design Plan — Unit 1: Project Scaffold & Infrastructure + +**Status**: Completed — NFR design patterns and logical components generated based on answers. + +## Plan Checklist +- [x] Analyze NFR requirements artifacts (nfr-requirements.md, tech-stack-decisions.md) +- [x] Identify design pattern decisions needed for performance, a11y, testing, i18n, config +- [x] Generate context-appropriate multiple-choice questions per question-format-guide.md +- [x] Store this plan file +- [x] Wait for user completion of [Answer] tags +- [x] Validate answers, resolve any ambiguities +- [x] Generate nfr-design-patterns.md and logical-components.md artifacts + +## NFR Design Questions + +## Question 1 +How should TanStack Router file-based routes be organized to achieve optimal code-splitting and keep the initial JS bundle as small as possible? + +A) One route file per major feature (auth, dashboard, users, cms) with lazy-loaded layouts and components +B) Flat structure under src/routes/ with all routes co-located, relying on Vite's automatic tree-shaking and code-splitting +C) Hybrid approach: core shell and auth routes eager-loaded; feature modules (dashboard, users, cms) lazy-loaded via dynamic imports inside authenticated layout +X) Other (please describe after [Answer]: tag below) + +[Answer]: A + +## Question 2 +What focus management and keyboard navigation pattern should be implemented for the admin UI (sidebar navigation + main content area) to satisfy the basic a11y requirement? + +A) Rely entirely on browser default Tab order + shadcn/ui :focus-visible styles; add focus trap only for modals and dialogs +B) Implement roving tabindex for sidebar nav items + visible focus ring; standard Tab for main content +C) Full custom arrow-key navigation and type-ahead search inside the sidebar (desktop-app style) +X) Other (please describe after [Answer]: tag below) + +[Answer]: A + +## Question 3 +How should MSW request handlers be organized to support auth flows, 401-intercept testing, and future feature mocks while keeping tests maintainable? + +A) Centralized `src/mocks/handlers.ts` exporting domain-specific arrays (authHandlers, userHandlers, cmsHandlers) re-exported from index +B) Feature-scoped folders under `src/mocks/` (e.g. `auth/handlers.ts`, `users/handlers.ts`) with barrel re-exports +C) Inline MSW handlers defined directly inside each test file for maximum isolation +X) Other (please describe after [Answer]: tag below) + +[Answer]: B + +## Question 4 +What strategy should be used for loading and switching between English and Dutch translations with react-i18next? + +A) Eager-load both language JSON files at app bootstrap (small total size) and keep them in memory +B) Lazy-load only the active language JSON; switch language by dynamic import of the new locale file +C) Use i18next-http-backend to fetch translations from `/locales/{lng}/{ns}.json` on demand (no bundling) +X) Other (please describe after [Answer]: tag below) + +[Answer]: B + +## Question 5 +How should RFC 9457 ProblemDetails responses be transformed into user-facing feedback (toasts/banners) while keeping the implementation simple? + +A) Global error interceptor in ApiClient that maps ProblemDetails to a single shadcn/ui toast (title = title or status, description = detail) +B) Per-page or per-component error handling that decides toast vs. inline message based on context +C) Only show toasts for network errors and 5xx; 4xx errors are handled by form validation or redirect only +X) Other (please describe after [Answer]: tag below) + +[Answer]: B + +## Question 6 +How should Vite environment variables (VITE_API_BASE_URL and future feature flags) be typed and validated? + +A) Extend `vite-env.d.ts` with a typed `import.meta.env` interface and add optional Zod validation at runtime startup +B) Use TypeScript module augmentation for `import.meta.env` only; no runtime validation (trust .env files) +C) Fetch a `config.json` at bootstrap for all non-Vite-exposed settings; keep VITE_* vars minimal +X) Other (please describe after [Answer]: tag below) + +[Answer]: A \ No newline at end of file diff --git a/aidlc-docs/features/cms-frontend/construction/plans/unit-1-nfr-requirements-plan.md b/aidlc-docs/features/cms-frontend/construction/plans/unit-1-nfr-requirements-plan.md index 78f53a1..ed2c080 100644 --- a/aidlc-docs/features/cms-frontend/construction/plans/unit-1-nfr-requirements-plan.md +++ b/aidlc-docs/features/cms-frontend/construction/plans/unit-1-nfr-requirements-plan.md @@ -1,15 +1,15 @@ # NFR Requirements Plan — Unit 1: Project Scaffold & Infrastructure -**Status**: Awaiting user answers to the questions below. +**Status**: Completed — NFR requirements and tech-stack decisions generated. ## Plan Checklist -- [ ] Analyze functional design artifacts (domain-entities.md, business-rules.md, business-logic-model.md) -- [ ] Identify NFR categories requiring clarification (performance, security, accessibility, maintainability, observability) -- [ ] Generate context-appropriate multiple-choice questions per question-format-guide.md -- [ ] Store this plan file -- [ ] Wait for user completion of [Answer] tags -- [ ] Validate answers, resolve any ambiguities -- [ ] Generate nfr-requirements.md and tech-stack-decisions.md artifacts +- [x] Analyze functional design artifacts (domain-entities.md, business-rules.md, business-logic-model.md) +- [x] Identify NFR categories requiring clarification (performance, security, accessibility, maintainability, observability) +- [x] Generate context-appropriate multiple-choice questions per question-format-guide.md +- [x] Store this plan file +- [x] Wait for user completion of [Answer] tags +- [x] Validate answers, resolve any ambiguities +- [x] Generate nfr-requirements.md and tech-stack-decisions.md artifacts ## NFR Questions diff --git a/aidlc-docs/features/cms-frontend/construction/unit-1/nfr-design/logical-components.md b/aidlc-docs/features/cms-frontend/construction/unit-1/nfr-design/logical-components.md new file mode 100644 index 0000000..0228188 --- /dev/null +++ b/aidlc-docs/features/cms-frontend/construction/unit-1/nfr-design/logical-components.md @@ -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. \ No newline at end of file diff --git a/aidlc-docs/features/cms-frontend/construction/unit-1/nfr-design/nfr-design-patterns.md b/aidlc-docs/features/cms-frontend/construction/unit-1/nfr-design/nfr-design-patterns.md new file mode 100644 index 0000000..4d9c57c --- /dev/null +++ b/aidlc-docs/features/cms-frontend/construction/unit-1/nfr-design/nfr-design-patterns.md @@ -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 `