Adds application design (awaiting approval)
This commit is contained in:
@@ -0,0 +1,155 @@
|
||||
# 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
|
||||
@@ -0,0 +1,145 @@
|
||||
# Execution Plan — CMS Frontend
|
||||
|
||||
## Detailed Analysis Summary
|
||||
|
||||
### Transformation Scope
|
||||
- **Transformation Type**: New greenfield frontend project within a brownfield workspace
|
||||
- **Primary Changes**: New React SPA (`frontend/`) with auth layer, routing, API client, 8+ pages, role-based access
|
||||
- **Related Components**: SlpModularCms.Api (REST consumer), existing example app (design reference only)
|
||||
|
||||
### Change Impact Assessment
|
||||
- **User-facing changes**: Yes — entire new admin interface
|
||||
- **Structural changes**: Yes — new `frontend/` project added to workspace root
|
||||
- **Data model changes**: No — frontend consumes existing API contracts
|
||||
- **API changes**: Yes — backend requires CORS configuration and httpOnly cookie support for refresh token (Unit 0, blocking)
|
||||
- **NFR impact**: Yes — Security Baseline enabled; auth token strategy, input validation, HTTP headers all addressed
|
||||
|
||||
### Risk Assessment
|
||||
- **Risk Level**: High → Mitigated to Medium after backend fixes
|
||||
- **Rollback Complexity**: Moderate — backend changes (CORS, httpOnly cookie) must be coordinated with frontend
|
||||
- **Testing Complexity**: Moderate — auth flows, role guards, invitation token states require careful testing
|
||||
|
||||
### Backend Blocking Issues Found (pre-flight inspection)
|
||||
1. **🔴 No CORS configuration** — `Program.cs` has no `app.UseCors()` or `builder.Services.AddCors()`. The frontend SPA (different origin) cannot make any API calls without a CORS error.
|
||||
2. **🟠 Refresh token via JSON body** — `AuthService` returns the refresh token in the response body and the `/auth/refresh` endpoint reads it from the request body. No httpOnly cookie support. This conflicts with NFR-04 (Security Baseline SECURITY-12).
|
||||
3. **🟡 JWT expiry: 60 minutes** — Acceptable; no action needed.
|
||||
|
||||
**Resolution**: Backend must be updated (Unit 0) before frontend development begins.
|
||||
|
||||
---
|
||||
|
||||
## Workflow Visualization
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["User Request"])
|
||||
|
||||
subgraph INCEPTION["🔵 INCEPTION PHASE"]
|
||||
WD["Workspace Detection\n✅ COMPLETED"]
|
||||
RE["Reverse Engineering\n✅ COMPLETED"]
|
||||
RA["Requirements Analysis\n✅ COMPLETED"]
|
||||
US["User Stories\n✅ COMPLETED"]
|
||||
WP["Workflow Planning\n⚙️ IN PROGRESS"]
|
||||
AD["Application Design\n▶️ EXECUTE"]
|
||||
UG["Units Generation\n▶️ EXECUTE"]
|
||||
end
|
||||
|
||||
subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"]
|
||||
FD["Functional Design\n▶️ EXECUTE (per unit)"]
|
||||
NFRA["NFR Requirements\n▶️ EXECUTE (Unit 1 only)"]
|
||||
NFRD["NFR Design\n▶️ EXECUTE (Unit 1 only)"]
|
||||
ID["Infrastructure Design\n⏭️ SKIP"]
|
||||
CG["Code Generation\n▶️ EXECUTE (per unit)"]
|
||||
BT["Build and Test\n▶️ EXECUTE"]
|
||||
end
|
||||
|
||||
subgraph OPERATIONS["🟡 OPERATIONS PHASE"]
|
||||
OPS["Operations\n⏸️ PLACEHOLDER"]
|
||||
end
|
||||
|
||||
Start --> WD --> RE --> RA --> US --> WP
|
||||
WP --> AD --> UG
|
||||
UG --> FD --> NFRA --> NFRD --> CG
|
||||
NFRD -.->|skip infra| CG
|
||||
ID -.->|skipped| CG
|
||||
CG -->|next unit| FD
|
||||
CG --> BT --> OPS --> End(["Complete"])
|
||||
|
||||
style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style RE fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style RA fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style US fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style WP fill:#FFA726,stroke:#E65100,stroke-width:3px,color:#000
|
||||
style AD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray:5 5,color:#000
|
||||
style UG fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray:5 5,color:#000
|
||||
style FD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray:5 5,color:#000
|
||||
style NFRA fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray:5 5,color:#000
|
||||
style NFRD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray:5 5,color:#000
|
||||
style ID fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray:5 5,color:#000
|
||||
style CG fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style OPS fill:#FFF9C4,stroke:#F57F17,stroke-width:2px,stroke-dasharray:5 5,color:#000
|
||||
style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
|
||||
style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phases to Execute
|
||||
|
||||
### 🔵 INCEPTION PHASE
|
||||
|
||||
- [x] Workspace Detection — COMPLETED
|
||||
- [x] Reverse Engineering (shared) — COMPLETED
|
||||
- [x] Requirements Analysis — COMPLETED
|
||||
- [x] User Stories — COMPLETED
|
||||
- [~] Workflow Planning — IN PROGRESS
|
||||
- [ ] **Application Design — EXECUTE**
|
||||
- **Rationale**: New project with multiple layers (auth context, API client, router, role guards, pages). Component responsibilities and service boundaries need to be defined before code generation.
|
||||
- [ ] **Units Generation — EXECUTE**
|
||||
- **Rationale**: The frontend consists of 6 logical units (scaffold, auth pages, layout, dashboard, user management, remaining pages) that benefit from being designed and implemented one at a time.
|
||||
|
||||
### 🟢 CONSTRUCTION PHASE (per unit)
|
||||
|
||||
- [ ] **Functional Design — EXECUTE (for each unit)**
|
||||
- **Rationale**: Each unit has business logic (auth flows, token refresh, role guards, invitation token validation) that needs to be designed before coding.
|
||||
- [ ] **NFR Requirements — EXECUTE (Unit 1 — Project Scaffold only)**
|
||||
- **Rationale**: Tech stack and security patterns are set in Unit 1. Subsequent units inherit these decisions; no need to re-evaluate NFRs per unit.
|
||||
- [ ] **NFR Design — EXECUTE (Unit 1 only)**
|
||||
- **Rationale**: Auth token storage pattern, API client interceptor, and error boundary design are foundational and should be explicitly designed once.
|
||||
- [ ] **Infrastructure Design — SKIP**
|
||||
- **Rationale**: No cloud infrastructure resources to define. The frontend is a static SPA served from a web server or CDN. Deployment instructions go in README.md per NFR-05.
|
||||
- [ ] **Code Generation — EXECUTE (per unit, always)**
|
||||
- **Rationale**: Implementation of each unit.
|
||||
- [ ] **Build and Test — EXECUTE**
|
||||
- **Rationale**: Build, type-check, lint, and verify all units work together.
|
||||
|
||||
### 🟡 OPERATIONS PHASE
|
||||
- [ ] Operations — PLACEHOLDER (future deployment/monitoring workflows)
|
||||
|
||||
---
|
||||
|
||||
## Proposed Unit Decomposition
|
||||
|
||||
| Unit | Name | Key Deliverables |
|
||||
|------|------|-----------------|
|
||||
| **Unit 0** | **Backend Prerequisites** | CORS policy (allow frontend origin, credentials), httpOnly cookie for refresh token (Set-Cookie on login/refresh, clear on revoke), update `/auth/refresh` to read token from cookie |
|
||||
| Unit 1 | Project Scaffold & Infrastructure | Vite + React + TypeScript project init, TanStack Router setup, shadcn/ui + Tailwind v4, auth context (in-memory access token), API client with interceptor, `.env` config |
|
||||
| Unit 2 | Authentication Pages | Login page, Setup (initialization) page, Invite Complete page, token refresh on 401 |
|
||||
| Unit 3 | Layout & Navigation | Authenticated layout shell, role-based sidebar, theme toggle (dark/light), ProtectedRoute + RoleGuard |
|
||||
| Unit 4 | Dashboard | Dashboard page with welcome widget and availability status indicator |
|
||||
| Unit 5 | User Management | Users list page, Invite user dialog, share invite link step |
|
||||
| Unit 6 | Profile, System Settings & CMS Placeholder | Profile page, System Settings page (Owner only), CMS placeholder page (Owner only), 404/403 pages, README.md frontend section |
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
- **Primary Goal**: Fully functional CMS admin SPA that connects to the existing .NET API
|
||||
- **Key Deliverables**: All 20 user stories implemented, INVEST-compliant acceptance criteria met
|
||||
- **Quality Gates**:
|
||||
- TypeScript compiles without errors
|
||||
- All routes protected with correct role guards
|
||||
- Auth flow (login → refresh → logout) works end-to-end
|
||||
- Password validation matches backend rules
|
||||
- Security baseline compliance maintained
|
||||
- README.md frontend section complete
|
||||
Reference in New Issue
Block a user