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

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

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

• Workspace Detection — COMPLETED
• Reverse Engineering (shared) — COMPLETED
• Requirements Analysis — COMPLETED
• 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