Adds the AI-DLC documents of the CMS and API foundation feature
Continuous Integration / check (pull_request) Successful in 1m50s
Continuous Integration / deploy-test (pull_request) Skipped
Continuous Integration / lighthouse (pull_request) Successful in 8m50s
Continuous Integration / deploy-production (pull_request) Skipped

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-08 02:06:00 +01:00
co-authored by Claude Sonnet 5.5
parent 41a6e7be5a
commit 288b0e3838
19 changed files with 1901 additions and 0 deletions
@@ -0,0 +1,90 @@
# Application Design Plan: cms-api-foundation
Depth: minimal-to-standard, contract level. Detailed business rules are for Functional Design (U1, by the CMS session).
## What the code reading showed (inputs to the design)
- **Module discovery** (`ModuleOrchestrator.DiscoverModules`) loads every `SlpModularCms.Modules.*.dll` found next to the host and instantiates each `IModule`. So today "which modules" = which projects the client `.csproj` references. There is no config filter yet. MVC controller discovery is a separate mechanism and must be filtered too, or a disabled module's routes can still answer.
- **`CmsHostOptions`** is an empty class, documented as the extension point for per-client differences, passed to both `CmsHost.ConfigureServices` and `ConfigurePipeline`.
- **Static content** (`StaticContentExtensions`) mounts `wwwroot/web` at `/` with `UseDefaultFiles` plus an extensionless SPA fallback to `index.html`. It does not map `/over-mij` to `over-mij.html` and does not serve `404.html` with status 404.
- **Security headers** are already per path: `SecurityHeadersOptions.PathPolicies` (first match wins) plus a code-defined `CspPolicyCatalog` with exactly two policies, `Strict` and `Relaxed`. `Strict` never gets extra script origins ("the admin SPA must not load script from anywhere but itself").
- **The site's CSP** (`web/config/securityHeaders.ts`) is `Strict`-like but needs the Umami script origin in `script-src` and the Umami and Sentry ingest origins in `connect-src`. So neither existing catalog policy matches it.
- **The site's build** (TanStack Start prerender) writes `over-mij.html`, `404.html` and `index.html` without folders, and externalizes inline scripts so the strict CSP works.
- **The site's current nginx/IIS config** (generated by `web/config/serverConfig.ts`, rules BR-HST-01 to 11) does more than serve files: canonical-URL 301 redirects (uppercase, `.html`, trailing slash), `404.html` with status 404, the header set, `Cache-Control: no-cache` for pages and long caching for hashed `/assets`, gzip for text types, and on test `X-Robots-Tag: noindex` plus a `robots.txt` that disallows everything. The CMS host has to take over what matters of this.
- **Admin build** already takes build-time variables (`VITE_APP_TITLE`, `VITE_API_BASE_URL`), so a per-site theme selector (`VITE_THEME`) fits the existing approach.
- **CI/CD** in the CMS repo: `.gitea/workflows/continuous_integration.yaml` and `deploy-scp.yaml`.
## Plan
- [x] Analyze requirements and read the CMS host code (read-only)
- [x] Collect answers to the design questions below
- [x] Analyze answers for ambiguity; ask follow-ups if needed (none: Q1 clarified in chat and applied to FR-2)
- [x] Generate `application-design/components.md`
- [x] Generate `application-design/component-methods.md`
- [x] Generate `application-design/services.md`
- [x] Generate `application-design/component-dependency.md`
- [x] Generate `application-design/application-design.md` (consolidated)
- [x] Validate design completeness and consistency (including Security Baseline check)
## Design questions
### Question 1: Module switch
How does a client choose its modules?
- A) Every client references all module projects; an allowlist in configuration (`Modules:Enabled`) decides which are active. The orchestrator skips the others and a controller filter removes their routes. Hosts without the setting behave as today (everything discovered is active). Enabling a module later is a config change. Recommended: matches the decision "configuration switch per module".
- B) Each client references only the modules it needs (what happens now). No new filter code, and unused module code is not on disk, but enabling a module later needs a code change and a new build.
- X) Other (describe after the [Answer]: tag below)
[Answer]: B (owner: a module is on when its DLL is added to the client; no config filter, and not all functionality is built into every client)
### Question 2: How the site's CSP is realised
- A) A third, code-defined policy in `CspPolicyCatalog` (working name `StrictSite`): the `Strict` directives plus the configured script and connect origins. `Strict` for the admin stays untouched. Recommended: keeps "code decides what a policy means" and does not loosen the admin.
- B) Let `Strict` accept the extra script origins. Fewer lines, but it weakens the admin's policy for every client.
- X) Other (describe after the [Answer]: tag below)
[Answer]: A
### Question 3: Keeping the two CSP definitions from drifting
The site's CSP lives in the web repo, the host's in the CMS repo.
- A) The web repo's existing deployment check (`web/deploy/verify-deployment.sh`) asserts that the deployed host sends exactly `contentSecurityPolicy('production')` from `securityHeaders.ts`. Drift fails the web deploy. Recommended: one extra assertion, no cross-repo coupling.
- B) The site build emits a manifest with its CSP, which the host reads at startup. No drift, but the site (not CMS code) then decides its own policy, which goes against the CMS's code-defined policy design.
- C) Document it only.
- X) Other (describe after the [Answer]: tag below)
[Answer]: A
### Question 4: How much of nginx's behaviour does the host take over
- A) Parity for what the site relies on: canonical-URL 301 redirects, `404.html` with status 404, `Cache-Control` (pages no-cache, `/assets` long), compression of text types, and on test `X-Robots-Tag: noindex` with a disallow-all `robots.txt` (configured per environment, so production does not get it). Recommended: otherwise the switch changes SEO behaviour and the test site could get indexed.
- B) Minimal: serve the files, `404.html` with status 404 and the security headers. Redirects, caching and compression follow before production.
- X) Other (describe after the [Answer]: tag below)
[Answer]: A
### Question 5: Where per-client behaviour is configured
- A) The serving mode (prerendered pages versus SPA fallback) is a property of `CmsHostOptions`, set in the client's `Program.cs` (a property of the client's code). Environment-dependent things (noindex on test, allowed origins, enabled modules) go in appsettings. Recommended.
- B) Everything in appsettings, including the serving mode.
- X) Other (describe after the [Answer]: tag below)
[Answer]: A
### Question 6: How a theme is applied to the admin
- A) A theme is a folder in the CMS `frontend/` (for example `themes/andreaslop/`) with a CSS file that overrides the existing tokens, plus logo and favicon. `VITE_THEME` selects it at build time; without it the default look stays. Recommended: smallest change to the current `index.css` tokens.
- B) The theme is a JSON file with tokens that a build step turns into CSS.
- X) Other (describe after the [Answer]: tag below)
[Answer]: A
### Question 7: How the brief reaches the CMS session
- A) The brief stays in this repo's AIDLC folder (single source). I message the CMS session the path and it reads it; the CMS session decides what to copy into its own AIDLC workspace. Recommended: no writes into the CMS repo's AIDLC files from here.
- B) I place a copy of the brief in the CMS repo's AIDLC folder.
- X) Other (describe after the [Answer]: tag below)
[Answer]: B (owner chose a copy in the CMS repo)
@@ -0,0 +1,203 @@
# Execution Plan: cms-api-foundation
## Detailed Analysis Summary
### Transformation Scope (Brownfield Only)
- **Transformation Type**: Architectural and infrastructure change across two repositories. The way Andrea's site is hosted changes from a static deployment (nginx on test, IIS on production) to being served by a CMS host. A new client host appears in the CMS repo.
- **Primary Changes**:
- CMS repo: new client project `Api.AndreaSlopFotografie`; prerendered-site mode plus per-client CSP (no module filter: the client csproj decides its modules) in the shared `CmsHost` (`SlpModularCms.Core`); per-site admin theme and admin build; CI builds the admin per client.
- This repo: the deploy of the site build into `wwwroot/web/` of the CMS host on test, and the web CI that does it.
- **Related Components**: `SlpModularCms.Core` (CmsHost), `SlpModularCms.Modules.*` (switchable), `SlpModularCms.Api.SlpSoftware` (regression), CMS `frontend/`, CMS Gitea CI/CD, this repo's `web/` build and CI, test host (Pi).
### Change Impact Assessment
- **User-facing changes**: Yes. The admin gets Andrea's look and Dutch default; the public site is served by a different host (URLs and content unchanged).
- **Structural changes**: Yes. Shared host gains a prerendered-site mode and per-client headers; new client project; deployment layout changes.
- **Data model changes**: Minimal. A new database for the new host with the existing Identity schema. No schema change to existing modules.
- **API changes**: No new business endpoints. `/api/v1/System/capabilities` reflects active modules.
- **NFR impact**: Yes. Security (CSP must not weaken, setup flow exposure, headers), performance (static serving, compression, caching), deployability.
### Component Relationships (Brownfield Only)
```mermaid
flowchart LR
WEB["web/ (this repo)<br/>prerendered site build"]
WCI["Web CI (this repo)"]
CORE["SlpModularCms.Core<br/>CmsHost (shared)"]
CLI["Api.AndreaSlopFotografie<br/>(new client host)"]
SLP["Api.SlpSoftware<br/>(regression check)"]
FE["CMS frontend/<br/>admin + themes"]
CCI["CMS CI/CD (Gitea)"]
PI["Test host (Pi)<br/>MariaDB + release dir"]
WEB --> WCI
WCI --> PI
CORE --> CLI
CORE --> SLP
FE --> CCI
CLI --> CCI
CCI --> PI
classDef changed fill:#FFA726,stroke:#E65100,stroke-width:2px,color:#000;
classDef newc fill:#4CAF50,stroke:#1B5E20,stroke-width:2px,color:#fff;
classDef guard fill:#BDBDBD,stroke:#424242,stroke-width:2px,color:#000;
class WCI,CORE,FE,CCI changed;
class CLI newc;
class SLP,WEB,PI guard;
```
Text alternative: The web build goes through the web CI to the test host; the shared CmsHost feeds the new Andrea client and the existing SlpSoftware client; the admin frontend and the client are deployed by the CMS CI to the same host. Orange = changed, green = new, grey = unchanged or regression guard.
| Component | Change type | Reason | Priority |
|---|---|---|---|
| `SlpModularCms.Core` (CmsHost) | Major | Prerendered mode, per-client CSP policy, hosting parity | Critical |
| `Api.AndreaSlopFotografie` | New | Andrea's host | Critical |
| CMS `frontend/` | Minor | Theme selection at build, default language | Important |
| CMS CI/CD | Minor | Per-client admin build | Important |
| `Api.SlpSoftware` | None (regression guard) | Must not change behaviour | Critical |
| Web CI and deploy (this repo) | Minor | Deliver the build to `wwwroot/web/` | Important |
| `web/` application code | None | Untouched; avoids conflict with Testimonials | n/a |
### Risk Assessment
- **Risk Level**: Medium-High. A shared host is changed (SlpSoftware is in production), the site hosting model changes, and two repositories with two parallel AIDLC workspaces and a parallel session (Testimonials) are involved.
- **Rollback Complexity**: Easy on test: nginx keeps serving the site until the new route is proven; the CMS deploy uses an atomic release switch.
- **Testing Complexity**: Complex. Needs the Pi, MariaDB, prerendered output and header checks.
## Workflow Visualization
```mermaid
flowchart TD
Start(["User Request"])
subgraph INCEPTION["🔵 INCEPTION PHASE"]
WD["Workspace Detection<br/><b>COMPLETED</b>"]
RE["Reverse Engineering<br/><b>SKIP</b>"]
RA["Requirements Analysis<br/><b>COMPLETED</b>"]
US["User Stories<br/><b>SKIP</b>"]
WP["Workflow Planning<br/><b>IN PROGRESS</b>"]
AD["Application Design<br/><b>EXECUTE</b>"]
UG["Units Generation<br/><b>EXECUTE</b>"]
end
subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"]
FD["Functional Design<br/><b>EXECUTE (CMS unit)</b>"]
NFRA["NFR Requirements<br/><b>EXECUTE (CMS unit)</b>"]
NFRD["NFR Design<br/><b>EXECUTE (CMS unit)</b>"]
ID["Infrastructure Design<br/><b>EXECUTE</b>"]
CG["Code Generation<br/>(Planning + Generation)<br/><b>EXECUTE</b>"]
BT["Build and Test<br/><b>EXECUTE</b>"]
end
subgraph OPERATIONS["🟡 OPERATIONS PHASE"]
DS["Deployment Setup<br/><b>EXECUTE</b>"]
MS["Monitoring Setup<br/><b>EXECUTE</b>"]
PRV["Production Readiness Validation<br/><b>EXECUTE</b>"]
end
Start --> WD
WD --> RA
RA --> WP
WP --> AD
AD --> UG
UG --> FD
FD --> NFRA
NFRA --> NFRD
NFRD --> ID
ID --> CG
CG --> BT
BT --> DS
DS --> MS
MS --> PRV
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 CG 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 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:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,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
style INCEPTION fill:#BBDEFB,stroke:#1565C0,stroke-width:2px
style CONSTRUCTION fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px
style OPERATIONS fill:#FFF59D,stroke:#F9A825,stroke-width:2px
linkStyle default stroke:#333,stroke-width:2px
```
Text alternative: Inception (detection, requirements, planning, application design, units), then Construction (functional design, NFR requirements and design, infrastructure design, code generation, build and test), then Operations (deployment, monitoring, production readiness). Green = done or always, orange dashed = executes conditionally, grey dashed = skipped.
## How the two repositories and AIDLC workspaces work together
- **This workspace** holds the cross-repo decisions, the briefs to the CMS session, the web-side unit, and the verification of the hand-back.
- **The CMS repo** has its own AIDLC workspace. For the CMS unit the Construction stages (Functional Design, NFR Requirements, NFR Design, Code Generation, CMS-side Build and Test) are executed **by the CMS session** in that workspace, with a brief from this workspace as input. Here we record the brief, the CMS session's approved design summary and the hand-back in `construction/cms-host/`.
- **Approvals** (per the collaboration decision): the owner approves the CMS requirements and design; this session answers web-side questions and escalates CMS-internal, security and data-model questions to the owner.
## Phases to Execute
### 🔵 INCEPTION PHASE
- [x] Workspace Detection (COMPLETED)
- [x] Reverse Engineering (SKIPPED)
- **Rationale**: Team agreement: no full refresh per feature; the CMS repo has its own artifacts.
- [x] Requirements Analysis (COMPLETED)
- [x] User Stories (SKIPPED)
- **Rationale**: One persona (the site administrator) and no user-experience design in this step; acceptance criteria are in the requirements (FR-14). Can be added on request.
- [x] Execution Plan (IN PROGRESS)
- [ ] Application Design - EXECUTE (minimal-to-standard depth)
- **Rationale**: New shared-host components (prerendered-site mode, per-client header policy, theme selection) and a client project need defined responsibilities, plus the deployment layout contract between the two repos. Detailed internal design stays with the CMS session.
- [ ] Units Planning - SKIP (merged into Units Generation; two units are enough)
- [ ] Units Generation - EXECUTE
- **Rationale**: Two units with different owners and an order: U1 CMS host (CMS repo), U2 site delivery (this repo).
### 🟢 CONSTRUCTION PHASE
Units: **U1 `cms-host`** (CMS repo, built by the CMS session) and **U2 `site-delivery`** (this repo). Order: U1 before U2; the `web/`-adjacent changes in U2 start only when the Testimonials feature has merged or overlap is ruled out.
- [ ] Functional Design - EXECUTE for U1, SKIP for U2
- **Rationale**: U1 has new behaviour (path-to-file resolution, canonical redirects, header policy). U2 is pipeline work with no business logic.
- [ ] NFR Requirements - EXECUTE for U1, SKIP for U2
- **Rationale**: Security Baseline applies (CSP, setup exposure, error handling, rate limiting) and PBT framework selection (PBT-09). U2's NFRs are covered by the requirements.
- [ ] NFR Design - EXECUTE for U1, SKIP for U2
- **Rationale**: Patterns for header policy per client, fail-closed behaviour and a drift guard for the CSP.
- [ ] Infrastructure Design - EXECUTE for U1 and U2
- **Rationale**: Release layout with `wwwroot/web/` outside the swapped directory, per-client admin build in CI, delivery of the site build, database for the new host, ports, and switching off the static nginx site on test.
- [ ] Code Generation - EXECUTE (ALWAYS), per unit
- **Rationale**: Implementation and tests (including PBT-02, 03, 07, 08 where applicable).
- [ ] Build and Test - EXECUTE (ALWAYS)
- **Rationale**: Cross-unit proof on test (FR-14), SlpSoftware regression, header and 404-status checks.
### 🟡 OPERATIONS PHASE
- [ ] Deployment Setup, Monitoring Setup, Production Readiness Validation - EXECUTE
- **Rationale**: Operations Configuration = Yes (decided at Requirements Analysis). Scope is test only; production readiness records what remains for production.
## Package Change Sequence (Brownfield Only)
1. `SlpModularCms.Core` (CmsHost: prerendered mode, per-client header policy, hosting parity) with tests. Critical path.
2. `Api.AndreaSlopFotografie` client project, appsettings, database. Depends on 1.
3. CMS `frontend/` theme selection and Andrea's theme. Parallel with 2.
4. CMS CI/CD: per-client admin build and deploy for the new host. Depends on 2 and 3.
5. This repo: web CI delivers the site build to the new host on test. Depends on 4.
6. Proof on test, then switch off the static test site.
## Module Update Strategy
- **Update Approach**: Sequential for the critical path (1, 2, 4, 5), parallel for the theme work (3).
- **Critical Path**: Core host changes block everything else.
- **Coordination Points**: The reserved paths and `wwwroot/web/` contract, the 404 page location, the CSP values, the admin build per client in CI.
- **Testing Checkpoints**: After step 1 (SlpSoftware regression, unit and integration tests), after step 4 (deployed admin and `/health`), after step 5 (FR-14 proof).
## Estimated Timeline
- **Total Phases**: 3 (Inception, Construction, Operations).
- **Estimated Duration**: Roughly 4 to 6 working sessions across both workspaces, depending on CMS CI complexity and the test host.
## Success Criteria
- **Primary Goal**: Andrea's site and a themed Dutch admin run from one CMS host on test, with `Offerings` off and the existing SlpSoftware host unaffected.
- **Key Deliverables**: `Api.AndreaSlopFotografie` (with only the needed module references); prerendered-site mode; per-client CSP; per-site admin theme and build; web delivery pipeline; updated CMS docs; briefs and hand-back records.
- **Quality Gates**: Security Baseline compliance (blocking), PBT partial rules, SlpSoftware regression tests green, FR-14 proof on test, site Lighthouse not lower than on nginx.
- **Integration Testing**: Site, admin and API served together from one host on test.
- **Operational Readiness**: Logging, health and alerting for the new host per the Operations phase.
@@ -0,0 +1,42 @@
# Unit of Work Plan: cms-api-foundation
Terminology: the CMS side is a set of modules of one deployable host; "unit of work" is a planning unit, not a deployable service. No user stories exist (skipped), so the story map maps requirements (FR/NFR) to units.
## Proposed decomposition
The execution plan named two units (U1 CMS host, U2 site delivery). The application design suggests a split of the CMS side, because the shared-host change (Core) is critical and must not regress `Api.SlpSoftware`, while the client project, theme and CI are new and isolated.
| Unit | Repo | Contents | Built by |
|---|---|---|---|
| U1 `core-site-hosting` | CMS | C2 `CmsHostOptions`, C3 prerendered site serving, C4 `StrictSite`, tests, CMS docs (`WEBSITE_WORKSPACE.md`, README) | CMS session |
| U2 `andreaslop-client` | CMS | C1 `Api.AndreaSlopFotografie`, C5 admin theme and default language, C6 CMS CI/CD for the new host | CMS session |
| U3 `site-delivery` | WEB (this repo) | C7 delivery job, C8 extended `verify-deployment.sh`, retiring the static test site | This session |
Order: U1, then U2, then U3. U3 starts after the Testimonials feature has merged or overlap is ruled out.
## Plan
- [x] Analyze requirements and application design
- [x] Collect answers to the questions below
- [x] Generate `application-design/unit-of-work.md`
- [x] Generate `application-design/unit-of-work-dependency.md`
- [x] Generate `application-design/unit-of-work-story-map.md` (requirements to units)
- [x] Validate unit boundaries and dependencies; ensure every FR/NFR belongs to a unit
## Questions
### Question 1: Splitting the CMS side
- A) Two units on the CMS side (U1 shared host, U2 Andrea's client), as in the table. Recommended: U1 has its own checkpoint (SlpSoftware regression, unit tests green) before the new client is built on it.
- B) One CMS unit covering both.
- X) Other (describe after the [Answer]: tag below)
[Answer]: A (two CMS units). Owner: the client project is named Api.AndreaSlopFotografie instead of Api.AndreaSlop.
### Question 2: Briefs to the CMS session
- A) One brief per CMS unit (U1, then U2 when U1 is hand-backed). Recommended: matches "one feature at a time" for the CMS session's AIDLC.
- B) One brief for both CMS units; the CMS session sequences them itself.
- X) Other (describe after the [Answer]: tag below)
[Answer]: B (one brief for both CMS units; the CMS session sequences them, with a hand-back checkpoint after U1)