# Execution Plan - andreaslop-site-hosting ## Detailed Analysis Summary ### Transformation Scope (Brownfield) - **Type**: Extension of the shared host (`SlpModularCms.Core`) plus one new deployable client, an admin theming mechanism and CI/CD for a second deployment target. No rewrite; existing clients (`Api`, `Api.SlpSoftware`) must behave exactly as before. - **Primary changes**: (U1) `WebsiteMode.PrerenderedPages` with nginx-parity serving, `StrictSite` CSP policy, `Website:NoIndex`; (U2) client `SlpModularCms.Api.AndreaSlopFotografie`, admin theme via `VITE_THEME`/`VITE_DEFAULT_LANGUAGE`, optional first-admin setup token, CI/CD to the test Pi. - **Related components**: Core (`CmsHost`, `CmsHostOptions`, `StaticContentExtensions`, `CspPolicyCatalog`, security headers), Modules.Identity (setup token), frontend (theme tokens, build), `.gitea/workflows/*`, README / `WEBSITE_WORKSPACE.md`. ### Change Impact Assessment - **User-facing changes**: Yes - public website served by the host (visitor), themed Dutch admin (site owner). - **Structural changes**: Yes - new client project, new options/middleware in Core. - **Data model changes**: No new entities. New database instance per site (`AndreaSlopFotografieTest`); existing migrations apply. Setup token is configuration, not data. - **API changes**: Setup endpoint gains an optional token requirement (only when configured). No other API change. - **NFR impact**: Yes - Security Baseline (blocking), PBT partial, performance of per-request path resolution, proxy/HTTP 1.0 behaviour. ### Component Relationships ```mermaid graph TD core["SlpModularCms.Core
(CmsHost, StaticContent, CSP catalog)"] api["SlpModularCms.Api"] slp["SlpModularCms.Api.SlpSoftware"] andrea["SlpModularCms.Api.AndreaSlopFotografie
(new client, U2)"] ident["Modules.Identity
(setup token)"] avail["Modules.Availability"] fe["frontend
(theme per site)"] ci["Gitea workflows
(CI + deploy-scp)"] pi["Test Pi
(port 5200)"] core -->|"unchanged behaviour"| api core -->|"unchanged behaviour"| slp core -->|"PrerenderedPages + StrictSite (U1)"| andrea andrea --> ident andrea -.->|"only if required"| avail fe -->|"VITE_THEME=asf"| andrea ci -->|"build + deploy (test only)"| andrea andrea --> pi classDef shared fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; classDef existing fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; classDef new fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; classDef ext fill:#d6bcfa,stroke:#553c9a,stroke-width:1px,color:#000; class core shared; class api,slp,ident,avail,fe existing; class andrea new; class ci,pi ext; ``` Text alternative: Core serves all clients; the new Andrea client uses the new website mode and policy, references Identity (Availability only if needed), gets a themed admin build and is deployed by CI to the test Pi. | Component | Change type | Reason | Priority | |---|---|---|---| | Core hosting | Major (additive) | New mode, middleware, policy | Critical | | Api, Api.SlpSoftware | None (regression-guarded) | Must stay unchanged | Critical | | Identity | Minor | Optional setup token | Important | | Frontend | Minor | Theme tokens, language default | Important | | CI/CD | Minor | Per-client admin build, second deploy target | Important | | Docs | Minor | README, WEBSITE_WORKSPACE.md | Important | ### Risk Assessment - **Risk level**: Medium. Shared host change touches every client (mitigated by default `SpaFallback` and regression tests); public-facing path handling (traversal / open redirect) is security-relevant; deployment on a Pi that is not yet provisioned. - **Rollback complexity**: Easy for code (feature flag by default off); moderate for the Pi (manual steps by Bryan, test only). - **Testing complexity**: Complex (PBT on pure functions, integration tests of the pipeline with a temp website root, theme visual/contrast check, deploy smoke test). ## Workflow Visualization ```mermaid flowchart TD Start(["Brief from CMS & API"]) subgraph INCEPTION["INCEPTION PHASE"] WD["Workspace Detection
COMPLETED"] RE["Reverse Engineering
SKIP (reuse)"] RA["Requirements Analysis
COMPLETED"] US["User Stories
SKIP"] WP["Workflow Planning
IN PROGRESS"] AD["Application Design
EXECUTE"] UG["Units Generation
EXECUTE (minimal)"] end subgraph CONSTRUCTION["CONSTRUCTION PHASE"] U1["Unit U1 core-site-hosting
FD, NFR Req, NFR Design, Code, per-unit build/test"] H1["Hand-back U1 + wait for go"] U2["Unit U2 andreaslop-client
NFR Req, NFR Design, Infra Design, Code, per-unit build/test"] H2["Hand-back U2"] BT["Build and Test (all units)
EXECUTE"] end subgraph OPERATIONS["OPERATIONS PHASE"] DS["Deployment Setup
EXECUTE"] MS["Monitoring Setup
EXECUTE"] PRV["Production Readiness Validation
EXECUTE"] end Start --> WD --> RE --> RA --> US --> WP --> AD --> UG --> U1 --> H1 --> U2 --> H2 --> BT --> DS --> MS --> PRV --> End(["Complete"]) style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff style RA fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff style WP fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff style RE fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 style US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,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 U1 fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 style U2 fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 style H1 fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 style H2 fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 style DS fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 style MS fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 style PRV fill:#FFA726,stroke:#E65100,stroke-width:3px,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 linkStyle default stroke:#333,stroke-width:2px ``` Text alternative: green = done/always, orange dashed = conditional EXECUTE, grey dashed = SKIP, purple = checkpoints with the requester. ## Phases to Execute ### INCEPTION - [x] Workspace Detection (COMPLETED) - [x] Reverse Engineering (SKIPPED - existing `_shared/reverse-engineering/` reused; key host files read directly) - [x] Requirements Analysis (COMPLETED, approved by Bryan) - [x] User Stories (SKIPPED per Q6) - [x] Workflow Planning (IN PROGRESS) - [ ] Application Design - EXECUTE - **Rationale**: New components (WebsiteMode option, path resolver, prerendered-site middleware, StrictSite policy, client project, theme mechanism, setup-token check). The requester expects Bryan's design approval. - [ ] Units Generation - EXECUTE (minimal; no separate Units Planning question round) - **Rationale**: The two units are fixed by the brief. Formalise them (scope, order, dependencies, hand-back gates) in `unit-of-work.md`. ### CONSTRUCTION (per unit; U2 only after the requester's "go") **U1 core-site-hosting** - [ ] Functional Design - EXECUTE: path-resolution rule table, canonical form, known-page set, 404 and reserved-prefix behaviour, noindex/robots rules. - [ ] NFR Requirements - EXECUTE: security (traversal, open redirect, header completeness), PBT properties (partial mode), performance of lookup, proxy/HTTP 1.0 compatibility. - [ ] NFR Design - EXECUTE (compact): caching of file existence / known-page refresh, middleware ordering, compression scope. - [ ] Infrastructure Design - SKIP: no infrastructure change in U1. - [ ] Code Generation - EXECUTE (plan + generation + automatic per-unit build/test, regression run of `Api`/`Api.SlpSoftware`) - [ ] Hand-back note U1, message to "CMS & API", **wait for go** **U2 andreaslop-client** - [ ] Functional Design - SKIP: no new business domain; theme token mapping and client composition are covered by Application Design and requirements. - [ ] NFR Requirements - EXECUTE: setup-token security, secrets handling, contrast/accessibility of the theme, login rate limiting. - [ ] NFR Design - EXECUTE (compact): token check placement, constant-time compare, configuration shape. - [ ] Infrastructure Design - EXECUTE: Pi layout, systemd user unit, env variables, database `AndreaSlopFotografieTest` / user `AndreaSlopFotografie`, ufw rule for port 5200, proxy-Pi route, Gitea secrets, both `wwwroot/web` delivery variants, manual-step list for Bryan; then notify "CMS & API" so the Pi-Main session can draft commands. - [ ] Code Generation - EXECUTE (client, theme, setup token, workflows; per-unit build/test) - [ ] Test deploy - only with Bryan's go in this session, test host only - [ ] Hand-back note U2 - [ ] Build and Test - EXECUTE (full solution, frontend build per theme, cross-unit integration, smoke checks) ### OPERATIONS (Operations Configuration = Yes) - [ ] Deployment Setup - EXECUTE - [ ] Monitoring Setup - EXECUTE - [ ] Production Readiness Validation - EXECUTE (for the test environment; production out of scope) ## Package Change Sequence 1. `SlpModularCms.Core` (+ `Core.Tests`) - U1 2. `Api` / `Api.SlpSoftware` regression run - U1 3. `SlpModularCms.Modules.Identity` (+ tests) - setup token (U2) 4. `frontend` theme and build variables - U2 5. `SlpModularCms.Api.AndreaSlopFotografie` (+ solution entry under Clients) - U2 6. `.gitea/workflows` (CI matrix per client, deploy to test) - U2 7. Docs (`README.md`, `WEBSITE_WORKSPACE.md`) - U1 and U2 ## Success Criteria - **Primary goal**: Andrea's prerendered site and a themed Dutch admin served by one SlpModularCms process on the test Pi, with behaviour matching today's nginx and the exact CSP. - **Key deliverables**: WebsiteMode + StrictSite in Core; new client; theme; setup token; CI/CD; hand-back notes; Pi manual-step list. - **Quality gates**: Security Baseline compliance per stage; PBT-02/03/07/08/09 satisfied; `Api` and `Api.SlpSoftware` green and unchanged; per-unit build/test; requester's "go" before U2; Bryan's approval of requirements and design; no push without Bryan's request; no production changes.