SLP_Software/slp-modular-cms

Files

T

Sluijsens 7e4397af4e Adds unit 1 functional design and answered nfr requirements questions and plan

2026-06-19 20:39:36 +02:00

2.7 KiB

Raw Blame History

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