# 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