146 lines
7.8 KiB
Markdown
146 lines
7.8 KiB
Markdown
# 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
|