slp-modular-cms/aidlc-docs/features/cms-frontend/inception/plans/application-design-plan.md

# Application Design Plan — CMS Frontend

## Design Scope
This plan covers the high-level component architecture for:
1. **Unit 0** — Backend prerequisites (CORS + httpOnly cookie — .NET changes to `SlpModularCms.Api`)
2. **Units 1–6** — React SPA frontend

---

## Design Checklist
- [x] Context analyzed (requirements.md + stories.md + backend inspection)
- [x] Questions generated
- [x] Questions answered
- [x] components.md generated
- [x] component-methods.md generated
- [x] services.md generated
- [x] component-dependency.md generated
- [x] application-design.md (consolidated) generated

---

## Identified Components (preliminary — to be validated by answers below)

### Backend (Unit 0)
- `CorsConfiguration` — CORS policy setup in `ServiceCollectionExtensions`
- `AuthController` (update) — Add `Set-Cookie` on login/refresh/revoke
- `AuthService` (update) — Read refresh token from cookie in `RefreshTokenAsync`

### Frontend (Units 1–6)
**Infrastructure layer**
- `ApiClient` — Centralised HTTP client with baseURL, auth headers, 401 interceptor
- `AuthContext` — React context holding in-memory access token + user info + session state
- `RouterConfig` — TanStack Router route tree with guards

**Auth & Guard components**
- `ProtectedRoute` — Redirects unauthenticated users to `/login`
- `RoleGuard` — Redirects users to access-denied if role insufficient
- `InitGuard` — Checks `/setup/status` and redirects to `/setup` if uninitialized

**Layout components**
- `AppLayout` — Authenticated shell with sidebar + main content area
- `Sidebar` — Role-filtered navigation links + logout + theme toggle
- `ThemeProvider` — next-themes wrapper for dark/light mode

**Page components**
- `LoginPage`, `SetupPage`, `InviteCompletePage` — Public/unauthenticated pages
- `DashboardPage` — Availability widget + welcome
- `UsersPage` — User list + invite dialog + share link dialog
- `ProfilePage` — Read-only user info
- `SettingsPage` — Owner-only system info
- `CmsPage` — Owner-only placeholder
- `NotFoundPage`, `AccessDeniedPage` — Error pages

---

## Clarification Questions

Please answer the following questions by filling in the letter choice after the `[Answer]:` tag.

---

### Question 1: State management approach
How should global application state (auth token, user info, availability status) be managed?

A) React Context API only — simple, no extra dependencies, sufficient for this app size
B) React Context API + Zustand — Context for auth, Zustand for other shared state (e.g. availability)
C) React Query / TanStack Query for all server state + Context for auth only
D) React Context API + TanStack Query for server state (API calls with caching)
X) Other (please describe after [Answer]: tag below)

[Answer]: D

---

### Question 2: API client library
Which library should be used for HTTP calls to the backend?

A) Native `fetch` API with a custom wrapper (no extra dependency)
B) Axios — popular HTTP client with interceptors, request cancellation
C) TanStack Query (React Query) — server state management + caching built-in
D) ky — modern fetch-based HTTP client, lightweight
X) Other (please describe after [Answer]: tag below)

[Answer]: C

---

### Question 3: Form validation library
Which library should handle form state and validation (already mentioned react-hook-form in NFR-01, but confirm)?

A) react-hook-form with zod schema validation — standard modern choice
B) react-hook-form with yup schema validation
C) react-hook-form only (no schema library — manual validation)
X) Other (please describe after [Answer]: tag below)

[Answer]: A

---

### Question 4: TanStack Router approach
Which routing style should be used with TanStack Router?

A) Code-based routing — define routes as objects in a central `routes.ts` file
B) File-based routing — file structure in `src/routes/` maps to URL structure (TanStack Router convention)
X) Other (please describe after [Answer]: tag below)

[Answer]: B

---

### Question 5: Backend — refresh token cookie name and path
What name and path should the httpOnly cookie use for the refresh token?

A) `refreshToken` with path `/api/v1/auth` — scoped to the auth endpoints only (more secure)
B) `refreshToken` with path `/` — available for all paths
C) `cms_refresh_token` with path `/api/v1/auth`
X) Other (please describe after [Answer]: tag below)

[Answer]: A

---

### Question 6: CORS allowed origins configuration
How should the CORS allowed origins be configured in the backend?

A) Via appsettings.json — e.g. `"AllowedOrigins": ["http://localhost:5173"]` configurable per environment
B) Hardcoded in `ServiceCollectionExtensions.cs` for development only
C) Via environment variable `CORS_ALLOWED_ORIGINS` read at startup
X) Other (please describe after [Answer]: tag below)

[Answer]: A, let the dotnet-appsettings skill help you manage these settings if needed

---

### Question 7: User data in auth context
What user data should be stored in the auth context after login?

A) Only `userId`, `email`, `role` (minimum needed for routing/guards)
B) Full user object: `id`, `email`, `naam`, `role`, `isActive`
C) JWT claims only — extract `userId` and `role` directly from the decoded token
X) Other (please describe after [Answer]: tag below)

[Answer]: B

---

### Question 8: Error boundary scope
Where should React Error Boundaries be placed?

A) One global error boundary at the app root only
B) Global error boundary + per-page boundaries for isolated page failures
C) Global error boundary + per-widget boundaries (e.g. availability widget on dashboard)
X) Other (please describe after [Answer]: tag below)

[Answer]: B