Adds unit 1 functional design and answered nfr requirements questions and plan

2026-06-19 20:39:36 +02:00
parent 8b6ffcecba
commit 7e4397af4e
5 changed files with 285 additions and 9 deletions
@@ -0,0 +1,66 @@
+# Business Rules — Unit 1: Project Scaffold & Infrastructure
+
+These rules define the expected behavior and guardrails for the frontend scaffold. They are binding for subsequent design and implementation steps.
+
+## BR-U1-01: Session Bootstrap
+- On app mount, attempt a silent refresh using the httpOnly cookie
+- If successful, hydrate `AuthContext` with `{ user, accessToken, expiresAt }`
+- On failure (401), ensure `guest` state
+
+## BR-U1-02: Access Token Handling
+- Store the `accessToken` only in memory (React state/context)
+- Never persist it in `localStorage`, `sessionStorage`, or cookies
+
+## BR-U1-03: HTTP Defaults
+- All API calls use `fetch` with `credentials: 'include'`
+- `Content-Type: application/json` when a body is present
+
+## BR-U1-04: 401 Intercept + Retry
+- On a `401 Unauthorized`, the `ApiClient` must first try `POST /api/v1/auth/refresh` (cookie-based)
+- If it succeeds, update the in-memory token and retry the original request once
+- If refresh fails, clear auth and redirect to `/login`
+
+## BR-U1-05: Router & Guards
+- Use TanStack Router
+- Protected routes live under `_authenticated.tsx` layout
+- Use a `beforeLoad` guard (or equivalent hook) to block unauthorized access and redirect to `/login`
+
+## BR-U1-06: Public Routes
+- `/login`, `/setup`, and invitation completion pages remain publicly accessible
+- When authenticated users hit `/login`, redirect to the dashboard
+
+## BR-U1-07: Theme & UI
+- Configure Tailwind v4 with primary color `#ac0000`
+- shadcn/ui components must use this primary color in the theme configuration
+
+## BR-U1-08: Error Handling
+- Parse API errors as RFC 9457 `ProblemDetails`
+- Show a user-friendly toast/banner
+- Do not display raw stack traces
+
+## BR-U1-09: API Base URL
+- Read the API base URL from `import.meta.env.VITE_API_BASE_URL`
+- Provide `.env.example` and document setup in README
+
+## BR-U1-10: Typing & Naming
+- Use TypeScript types that align with backend payloads
+- The user property is named `name` (not `naam`)
+
+## BR-U1-11: Testing Readiness
+- Add stable `data-testid` attributes to interactive elements (e.g., `login-form-submit-button`) to support automation
+
+## BR-U1-12: Formatting
+- Use ESLint + Prettier
+- Enforce 4-space indentation (printWidth and other defaults as sensible)
+
+## BR-U1-13: Security
+- Never echo refresh tokens
+- Ensure all cross-origin calls rely on CORS allowlist and credentialed requests only
+
+## BR-U1-14: State Consistency
+- When auth state changes (login, refresh, logout), notify dependents via context
+- UI updates immediately without hard reloads
+
+## BR-U1-15: Network Robustness
+- The `ApiClient` must gracefully handle network timeouts and show non-blocking toasts
+- Background refetches should not break the UI