# 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