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

• Context analyzed (requirements.md + stories.md + backend inspection)
• Questions generated
• Questions answered
• components.md generated
• component-methods.md generated
• services.md generated
• component-dependency.md generated
• 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)

---

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)

---

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)

---

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)

---

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)

---

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)

---

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)