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,43 @@
# Application Design: cms-api-foundation (consolidated)
Details: [components.md](components.md), [component-methods.md](component-methods.md), [services.md](services.md), [component-dependency.md](component-dependency.md).
## Summary
Andrea's site runs from a new client host, `SlpModularCms.Api.AndreaSlopFotografie`, in the CMS repo. The host serves the admin (`/admin`), the API (`/api/v1`) and the prerendered site (`/`) in one process. Additive changes to the shared host give it a prerendered-site mode with the hosting behaviour nginx provides today, and a third code-defined CSP policy, `StrictSite`. The admin gets a per-site theme and default language through build-time variables. The web repo gains a delivery job and an extended deployment check that doubles as the CSP drift guard.
## Design decisions
| # | Decision | Consequence |
|---|---|---|
| D1 | A site's modules = the module projects its client references (existing DLL mechanism). No config filter. | No new filter code. Andrea does not reference `Offerings`; adding the reference later switches it on. Requirements FR-2 updated accordingly. |
| D2 | New policy `StrictSite` in `CspPolicyCatalog`. | Admin `Strict` unchanged. Site CSP equals the current nginx one when the origin lists match. |
| D3 | CSP drift guard = exact-CSP assertion in the web repo's `verify-deployment.sh`. | Cross-repo coupling stays in one script; drift fails the web deploy. |
| D4 | Hosting parity for what the site relies on: canonical redirects, `404.html` with status 404, cache rules, text compression, per-environment `noindex` and `robots.txt`. | The host replaces nginx without changing SEO behaviour; test is not indexed. |
| D5 | Serving mode is code (`CmsHostOptions` in the client's `Program.cs`); environment-dependent settings are appsettings. | `SpaFallback` stays the default, so `Api` and `Api.SlpSoftware` do not change. |
| D6 | Theme = folder with CSS token overrides and assets, selected with `VITE_THEME`; default language with `VITE_DEFAULT_LANGUAGE`. | One admin source tree, one build per client; no theme API. |
| D7 | The brief lives in this repo and a copy is placed in the CMS repo's AIDLC folder. | The location inside the CMS workspace is agreed with the CMS session when handing over. |
| D8 | Reserved prefixes (`/admin`, `/api/v1`, `/health`) are never handled by the website middleware. | An unknown API path remains an API 404 instead of the site's 404 page. |
## Security Baseline compliance (design level)
| Rule | Status | Note |
|---|---|---|
| SECURITY-04 headers | Compliant by design | `StrictSite` carries a restrictive CSP (no `unsafe-inline` in `script-src`, no `unsafe-eval`); HSTS, nosniff, DENY and Referrer-Policy come from the existing header writer. To confirm in Functional Design: HSTS is emitted for the website path. `style-src 'unsafe-inline'` is the existing, documented exception (Chakra/Emotion runtime styles). |
| SECURITY-05 input validation | Compliant by design | The only new input is the request path: the resolver is total, rejects traversal and never leaves the website root. Property tests (PBT-03 invariants) planned. |
| SECURITY-08 access control | Compliant | The site is public by intent; `/admin` and `/api/v1` unchanged. |
| SECURITY-09 hardening | To verify | No directory listing (resolver serves files only); generic errors by the existing handler. The first-administrator setup endpoint on the new instance must be protected until the first admin exists (NFR/FR-11), assessed in NFR Requirements. |
| SECURITY-10 supply chain | Compliant | No new dependencies (built-in response compression); lock files stay committed. |
| SECURITY-11 secure design | Compliant | Security logic stays in dedicated catalog and header components. Misuse case: path traversal and cache poisoning through non-canonical URLs, handled by the resolver. Rate limiting stays on login. |
| SECURITY-13 integrity | Compliant | Delivery is by the pipelines; CSP drift guard added. |
| SECURITY-15 fail safe | Compliant | Unknown policy names fail startup; missing `404.html` falls back to a plain 404. |
| SECURITY-01, 02, 03, 06, 07, 14 | Deferred | Assessed in NFR Requirements and Infrastructure Design (database TLS, proxy access logs, deploy identity, network exposure, alerting). |
No blocking security findings at this stage.
## Open items for the next stages
- Which module projects the new host must reference at minimum (Identity and Availability dependency) is a Functional Design finding of the CMS session.
- Exact canonicalisation rules and the file-resolution order are Functional Design, derived from `web/config/canonicalUrls.ts` and the web's BR-HST rules.
- Whether the test host's existing reverse proxy (nginx on the Pi) stays in front of the CMS host (TLS, access logs) is decided in Infrastructure Design.
- Node/SSR remains undecided and is outside step 0 (requirements Q2).
@@ -0,0 +1,85 @@
# Component Dependencies: cms-api-foundation
## Dependency matrix
Rows depend on columns ("x" = depends on).
| | C1 host | C2 options | C3 site serving | C4 StrictSite | C5 theme | C6 CMS CI | C7 delivery | C8 verify |
|---|---|---|---|---|---|---|---|---|
| **C1 Api.AndreaSlopFotografie** | | x | x (via CmsHost) | x (config) | | | | |
| **C2 CmsHostOptions** | | | | | | | | |
| **C3 Site serving** | | x | | | | | | |
| **C4 StrictSite** | | | | | | | | |
| **C5 Theme** | | | | | | | | |
| **C6 CMS CI** | x | | | | x | | | |
| **C7 Site delivery** | x (target) | | | | | x (host exists) | | |
| **C8 Verify** | x (live) | | x (behaviour) | x (behaviour) | | | x | |
## Dependency diagram
```mermaid
flowchart LR
C2["C2 CmsHostOptions"]
C3["C3 Prerendered site serving"]
C4["C4 StrictSite policy"]
C1["C1 Api.AndreaSlopFotografie"]
C5["C5 Admin theme"]
C6["C6 CMS CI"]
C7["C7 Site delivery (web repo)"]
C8["C8 Deployment verification (web repo)"]
C3 --> C2
C1 --> C2
C1 --> C3
C1 --> C4
C6 --> C1
C6 --> C5
C7 --> C6
C8 --> C7
C8 -. checks .-> C3
C8 -. checks .-> C4
classDef cms fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
classDef web fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
classDef newc fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
class C2,C3,C4,C5,C6 cms;
class C7,C8 web;
class C1 newc;
```
Text alternative: The new client host depends on the options, site serving and the StrictSite policy; the CMS CI builds the host and theme; the web repo's delivery depends on the CMS CI having deployed the host; verification checks the live behaviour of serving and policy. Blue = CMS repo, green = web repo, yellow = new client host.
## Communication patterns
- **Compile time**: the client project references `Core` and its modules (this is also what selects the modules). `CmsHostOptions` is passed in code.
- **Configuration**: `SecurityHeaders` and `Website` sections per environment (appsettings; no secrets).
- **Build time**: the admin reads `VITE_*` variables; nothing about the theme reaches the API.
- **Deploy time**: the CMS CI delivers the release; the web CI delivers site files into `wwwroot/web/`. The two never write into each other's directories.
- **Runtime**: the browser calls the host same-origin for everything (site, `/admin`, `/api/v1`); no CORS for the site.
## Data flow: a request for a site page
```mermaid
flowchart TD
R["Browser request /over-mij"]
H["Security headers (StrictSite)"]
RES["PrerenderedPathResolver"]
F["Serve over-mij.html"]
RD["301 to canonical path"]
NF["404.html, status 404"]
R --> H --> RES
RES -->|file found| F
RES -->|non-canonical form| RD
RES -->|unknown| NF
classDef step fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
classDef ok fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
classDef bad fill:#fc8181,stroke:#c53030,stroke-width:1px,color:#000;
class R,H,RES step;
class F,RD ok;
class NF bad;
```
Text alternative: A page request gets the security headers, then the path resolver decides between serving the page file, redirecting to the canonical URL or returning the 404 page with status 404.
## Cross-session dependencies
- C7 and C8 changes in `web/deploy` and CI are the only web-repo changes; they start after the Testimonials feature has merged or overlap is ruled out.
- C1 to C6 are built by the CMS session; their approved design and hand-back are recorded in `construction/cms-host/`.
@@ -0,0 +1,86 @@
# Component Methods: cms-api-foundation
High-level signatures only. Business rules (exact canonicalisation, edge cases, error handling) are defined in Functional Design by the CMS session. Names are indicative; the CMS session may rename them.
## C2. `CmsHostOptions`
```csharp
public enum WebsiteMode { SpaFallback = 0, PrerenderedPages = 1 }
public sealed class CmsHostOptions
{
public WebsiteMode WebsiteMode { get; init; } = WebsiteMode.SpaFallback;
}
```
## C3a. `PrerenderedPathResolver` (pure)
```csharp
public abstract record SiteResolution;
public sealed record ServeFile(string RelativePath, bool IsPage) : SiteResolution; // IsPage drives cache policy
public sealed record RedirectTo(string CanonicalPath) : SiteResolution; // 301, query added by caller
public sealed record NotFound() : SiteResolution;
public sealed class PrerenderedPathResolver
{
public PrerenderedPathResolver(Func<string, bool> fileExists);
public SiteResolution Resolve(PathString requestPath); // total: never throws, never escapes the root
}
```
## C3b. Middleware wiring
```csharp
public static IApplicationBuilder UseCmsPrerenderedSite(this WebApplication app, CmsHostOptions options);
// - registered where UseCmsStaticContent registers the website mount
// - skips reserved prefixes: /admin, /api/v1, /health
// - NotFound -> serve 404.html with status 404 (plain 404 if 404.html is missing)
```
## C3c. `WebsiteCachePolicy`
```csharp
public static string CacheControlFor(SiteResolution resolution); // pages: "no-cache"; /assets/*: long-lived immutable; other files: short default
```
## C3d. `WebsiteIndexingPolicy`
```csharp
public sealed class WebsiteOptions { public bool NoIndex { get; set; } } // section "Website"
public static IEndpointRouteBuilder MapCmsRobots(this IEndpointRouteBuilder app, WebsiteOptions options);
// NoIndex: adds X-Robots-Tag header to website responses and answers /robots.txt "User-agent: *\nDisallow: /"
```
## C4. `CspPolicyCatalog`
```csharp
public const string StrictSite = "StrictSite";
public static SecurityHeaderSet Build(string policy, IEnumerable<string> scriptOrigins, IEnumerable<string> connectOrigins);
// StrictSite: script-src 'self' + scriptOrigins; connect-src 'self' + connectOrigins; FrameOptions "DENY".
// Strict and Relaxed unchanged. KnownPolicies includes StrictSite.
```
## C1. `Api.AndreaSlopFotografie/Program.cs`
```csharp
var orchestrator = CmsHost.ConfigureServices(builder, new CmsHostOptions { WebsiteMode = WebsiteMode.PrerenderedPages });
var app = builder.Build();
CmsHost.ConfigurePipeline(app, orchestrator, new CmsHostOptions { WebsiteMode = WebsiteMode.PrerenderedPages });
```
## C5. Admin theme selection (build time)
```text
VITE_THEME -> frontend/themes/<name>/theme.css (+ logo, favicon); unset = default theme
VITE_DEFAULT_LANGUAGE -> "nl" | "en"; unset = current default
VITE_APP_TITLE -> existing
```
## C8. Deployment verification (shell, extends the existing script)
```text
verify_csp_equals <url> <expectedCsp> # expectedCsp generated from contentSecurityPolicy('production')
verify_status <url> <expectedStatus>
verify_redirect <url> <expectedLocation>
verify_header <url> <name> <expectedValue|absent>
```
@@ -0,0 +1,64 @@
# Components: cms-api-foundation
Repository: **CMS** = `K:\Development\Projects\SlpModularCms`, **WEB** = this repo. Components marked "new" do not exist yet; "changed" exist and get an additive change. Everything under CMS is built by the CMS session in its own AIDLC; it may rename types, the responsibilities and interfaces are the contract.
## CMS repo
### C1. `SlpModularCms.Api.AndreaSlopFotografie` (new, client host)
- **Purpose**: The deployable host for Andrea's site: admin, API and the prerendered website in one process.
- **Responsibilities**:
- Thin `Program.cs` on the shared `CmsHost`, like `Api.SlpSoftware`.
- Module composition: references `Core` and only the module projects Andrea needs. `Offerings` is not referenced. Which other modules are required (Identity, and possibly Availability) is a Functional Design finding of the CMS session.
- Sets `CmsHostOptions.WebsiteMode = PrerenderedPages`.
- Own appsettings (three-file pattern), own database, own dev port.
- Security header configuration: `SecurityHeaders:DefaultPolicy = StrictSite` and `AllowedScriptOrigins` / `AllowedConnectOrigins` for Umami and Sentry.
- Website indexing setting (`Website:NoIndex`) per environment.
- **Interfaces**: the shared `CmsHost.ConfigureServices` / `ConfigurePipeline` calls; configuration sections `SecurityHeaders`, `Website`.
### C2. `CmsHostOptions` (changed, in Core)
- **Purpose**: The documented extension point for per-client differences.
- **Responsibilities**: carries `WebsiteMode` (`SpaFallback` default, `PrerenderedPages`). The default keeps `Api` and `Api.SlpSoftware` unchanged.
- **Interface**: `WebsiteMode WebsiteMode { get; init; }`.
### C3. Prerendered website serving (new, in Core `Hosting`)
Four parts, replacing the website half of `UseCmsStaticContent` and `MapCmsSpaFallbacks` when `WebsiteMode = PrerenderedPages`:
- **C3a `PrerenderedPathResolver`** (pure function, no I/O beyond a file-existence predicate): maps a request path to one of `Serve(file)`, `Redirect(canonicalPath)`, `NotFound`. Rules: `/` serves `index.html`; `/x` serves `x.html` (also `x/index.html` if present); canonical form is lowercase, without `.html`, without trailing slash, query preserved; paths that look like a file are served as files or 404; traversal attempts never leave the website root; reserved prefixes (`/admin`, `/api/v1`, `/health`) are never handled here.
- **C3b `PrerenderedSiteMiddleware`**: applies the resolver, serves files, answers `404.html` with status 404 for unknown paths (never `index.html`), issues canonical 301 redirects, and excludes reserved prefixes so an unknown `/api/v1/x` stays a plain API 404, not the website's 404 page.
- **C3c `WebsiteCachePolicy`**: `Cache-Control: no-cache` for pages, long-lived immutable for hashed `/assets`.
- **C3d `WebsiteIndexingPolicy`**: when `Website:NoIndex` is true, adds `X-Robots-Tag: noindex, nofollow` and serves `/robots.txt` as "disallow all". Off by default.
- **Compression** uses the built-in ASP.NET response compression for the same text types as `web/config/compressibleTypes.ts`; no new dependency.
### C4. `CspPolicyCatalog.StrictSite` (changed, in Core `Hosting/Security`)
- **Purpose**: The third code-defined policy for a strict, script-from-self public site.
- **Responsibilities**: `Strict` directives plus configured script origins in `script-src` and configured connect origins in `connect-src`; `X-Frame-Options: DENY`; `frame-ancestors 'none'`. `Strict` and `Relaxed` do not change. `PathPolicyRule` and startup validation accept the new name (unknown names still fail startup).
- **Interface**: `CspPolicyCatalog.Build("StrictSite", scriptOrigins, connectOrigins) -> SecurityHeaderSet`.
### C5. Admin theming (changed, CMS `frontend/`)
- **Purpose**: Make the admin match a site's identity without per-site code.
- **Responsibilities**:
- Default theme = today's tokens in `index.css`.
- A theme folder `frontend/themes/<name>/` with a CSS file overriding the tokens (colours, radius, font) and the assets (logo, favicon).
- `VITE_THEME` selects the folder at build time; `VITE_APP_TITLE` already names the app; a new build-time `VITE_DEFAULT_LANGUAGE` sets the default admin language (NL for Andrea, EN remains selectable).
- First theme: `themes/andreaslop/` from the site's identity (source: `design/andreaslop-static/` and the web theme in this repo).
- **Interface**: build-time environment variables only. No API.
### C6. CMS CI/CD (changed, `.gitea/workflows/continuous_integration.yaml`, `deploy-scp.yaml`)
- **Purpose**: Build and deploy Andrea's host.
- **Responsibilities**: build the admin once per deployable client with its `VITE_THEME` / `VITE_DEFAULT_LANGUAGE` / `VITE_APP_TITLE`; publish `Api.AndreaSlopFotografie`; deploy to the test host with the existing atomic release switch; keep `wwwroot/web/` outside the swapped release directory.
## WEB repo (this repo)
### C7. Site delivery (new)
- **Purpose**: Get the prerendered build onto Andrea's CMS host.
- **Responsibilities**: a CI job that builds the site and delivers the output (`index.html`, `*.html`, `404.html`, `assets/`, `robots`/sitemap files as built) to `wwwroot/web/` of the test host; keeps the old nginx deployment until the new route passes; afterwards retires the static test site.
- **Interface**: file delivery into `wwwroot/web/` (the contract in the CMS repo's `WEBSITE_WORKSPACE.md`).
### C8. Deployment verification (changed, `web/deploy/verify-deployment.sh`)
- **Purpose**: Prove the new host serves the site as the old one did, and guard CSP drift.
- **Responsibilities**: assert the exact CSP from `contentSecurityPolicy('production')` (`web/config/securityHeaders.ts`) and the other security headers; assert canonical redirects, `404.html` with status 404, caching and `noindex` on test; assert that `/admin`, `/api/v1/System/capabilities` and `/health` respond.
## Process component
### C9. Hand-off (new, documents)
- **Purpose**: Moves a feature brief to the CMS session and brings the result back.
- **Responsibilities**: the brief is written in this repo's AIDLC folder and a copy is placed in the CMS repo's AIDLC folder (owner decision). The CMS session runs its own AIDLC. The hand-back is a changelog plus the changed contract, verified here by the C8 checks.
@@ -0,0 +1,54 @@
# Services: cms-api-foundation
The solution has no new domain services: step 0 adds hosting behaviour (middleware and policy) and build/deploy automation. This document defines the orchestration points.
## S1. Host composition (`CmsHost`)
- **Responsibility**: single place where a client host's services and pipeline are composed. `ConfigureServices` and `ConfigurePipeline` keep their signatures; the new behaviour enters through `CmsHostOptions`.
- **Orchestration (pipeline order, with the reason)**:
1. `MigrateCoreDatabase` (unchanged).
2. Exception handler, then security headers, then rate limiter (unchanged). Security headers must stay before static content: static files short-circuit the pipeline, and the website's HTML is almost all the host serves.
3. HTTPS redirection (unchanged).
4. **Static content**: admin mount first (unchanged). The website mount is either the existing static mount plus SPA fallback (`SpaFallback`) or the prerendered-site middleware (`PrerenderedPages`). Response compression sits before both.
5. CORS, modules, authentication, authorization, controllers, health, Sentry tunnel (unchanged).
6. The website fallback (`NotFound` -> `404.html`) is the last step, after the API routes, so an unknown API path stays an API 404.
- **Invariant**: reserved prefixes `/admin`, `/api/v1`, `/health` are never resolved by the website middleware.
## S2. Security header resolution (existing `PathPolicyResolver` + `CspPolicyCatalog`)
- **Responsibility**: path -> policy name (configuration) -> header values (code).
- **Change**: the catalog knows `StrictSite`. Andrea's client sets `DefaultPolicy = StrictSite`; the three reserved prefixes stay `Strict`. Startup validation rejects unknown names (unchanged), so a typo cannot produce a weaker policy.
## S3. Build and deploy service chain (CI)
```mermaid
sequenceDiagram
box rgba(246,224,94,0.4) CMS repo
participant CC as CMS CI
end
box rgba(99,179,237,0.4) Web repo
participant WC as Web CI
end
box rgba(154,230,180,0.4) Test host
participant H as Andrea CMS host
end
CC->>CC: build admin with VITE_THEME andreaslop
CC->>CC: publish Api.AndreaSlopFotografie
CC->>H: deploy release, atomic switch
WC->>WC: build prerendered site
WC->>H: deliver files to wwwroot/web
WC->>H: verify headers, redirects, 404, CSP
H-->>WC: results
```
Text alternative: the CMS CI builds and deploys the host with its themed admin; the web CI builds the site, delivers it into the host's website folder and then verifies the host's behaviour.
- **Ordering rules**: the CMS release switch never touches `wwwroot/web/`; the web delivery is idempotent and can run without a CMS deploy; the old static test site stays up until verification passes.
## S4. Verification service (`verify-deployment.sh`)
- **Responsibility**: the contract test between the repositories. It runs from the web repo against the live host and is the CSP drift guard (design decision Q3).
## S5. Hand-off service (process)
- **Responsibility**: brief out, hand-back in; see C9. The CMS session's AIDLC outputs (its design summary and its hand-back note) are copied or linked under `construction/cms-host/` in this feature.
@@ -0,0 +1,38 @@
# Unit of Work Dependencies: cms-api-foundation
## Dependency matrix
Rows depend on columns.
| | U1 core-site-hosting | U2 andreaslop-client | U3 site-delivery |
|---|---|---|---|
| **U1 core-site-hosting** | | | |
| **U2 andreaslop-client** | x (code: `WebsiteMode`, `StrictSite`) | | |
| **U3 site-delivery** | | x (a deployed host to deliver into and verify) | |
## Diagram
```mermaid
flowchart LR
U1["U1 core-site-hosting<br/>(CMS repo)"]
U2["U2 andreaslop-client<br/>(CMS repo)"]
U3["U3 site-delivery<br/>(web repo)"]
CP1{{"Checkpoint: hand-back after U1"}}
U1 --> CP1 --> U2 --> U3
classDef cms fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
classDef web fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
classDef gate fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
class U1,U2 cms;
class U3 web;
class CP1 gate;
```
Text alternative: U1 and U2 are built in the CMS repo, with a hand-back checkpoint after U1; U3 in the web repo follows U2. Blue = CMS repo, green = web repo, yellow = checkpoint.
## Sequence and coordination
- **Critical path**: U1, U2, U3. No parallelism between units, because each needs the previous one's result; inside U2 the admin theme can be built in parallel with the host project.
- **Checkpoint after U1**: `Api` and `Api.SlpSoftware` tests green and the hand-back note delivered. U2 starts only then (the brief for both units tells the CMS session to report here).
- **Coordination points**: the reserved paths and the `wwwroot/web/` contract; the 404 page name (`404.html`) and the page files without folders (`name.html`); the exact CSP value (checked by U3); the host name and database of the test instance (decided in U2 Infrastructure Design).
- **External dependency for U3**: the Testimonials feature merged, or overlap ruled out, because U3 touches the web CI and `web/deploy/`.
- **Rollback**: U1 is additive and inactive by default (`SpaFallback`); U2 deploys a new host alongside the old test site; U3 retires the static test site only after verification, so every step can be reverted on test without data loss.
@@ -0,0 +1,35 @@
# Unit of Work Requirement Map: cms-api-foundation
User Stories were skipped (one persona; see the execution plan). This map assigns each requirement to its unit(s) instead. "Primary" owns the work; "also" contributes or verifies.
| Requirement | Summary | Primary unit | Also |
|---|---|---|---|
| FR-1 | Client project `Api.AndreaSlopFotografie` | U2 | |
| FR-2 | Module set = referenced module projects | U2 | |
| FR-3 | Existing hosts unchanged | U1 | U2 (SlpSoftware still builds and deploys) |
| FR-4 | Per-site theme file, selected at build | U2 | |
| FR-5 | Admin built per client in CI | U2 | |
| FR-6 | Andrea's theme matches the site | U2 | |
| FR-7 | Default admin language per site | U2 | |
| FR-8 | Prerendered-site serving mode | U1 | |
| FR-9 | SPA fallback remains available | U1 | |
| FR-10 | CSP for `/` per client, no drift | U1 (policy) | U2 (configuration), U3 (drift check) |
| FR-11 | Authentication unchanged, setup flow safe | U2 | |
| FR-12 | Site build delivered to `wwwroot/web/` | U3 | U2 (target host) |
| FR-13 | Web CI adapted, static test site retired after proof | U3 | |
| FR-14 | Proof on test | U3 | Build and Test (phase level) |
| FR-15 | Collaboration with the CMS session | Process (this session) | all units |
| NFR-1 | Security Baseline | all units | U2 (setup flow, logging), U1 (headers, path input) |
| NFR-2 | No security regression | U1 | U3 (exact CSP check) |
| NFR-3 | Performance (compression, caching, Lighthouse) | U1 | U3 (Lighthouse comparison) |
| NFR-4 | Compatibility with existing hosts | U1 | |
| NFR-5 | Deployability on the Pi, atomic switch | U2 | U3 |
| NFR-6 | Testing incl. partial PBT | U1 | U2 |
| NFR-7 | Per-site differences only in client and theme | U2 | U1 |
| NFR-8 | Documentation | U1 | U2 |
## Validation
- Every FR (1 to 15) and NFR (1 to 8) is assigned to a unit or to the process.
- Every component C1 to C8 belongs to exactly one unit: C2, C3, C4 to U1; C1, C5, C6 to U2; C7, C8 to U3. C9 (hand-off) is the process component.
- No unit depends on a later unit.
@@ -0,0 +1,37 @@
# Units of Work: cms-api-foundation
Three units. Terminology: a unit is a planning and build unit of one deployable system (the CMS host plus its admin) split into logical chunks; nothing here becomes an independently deployable service. Repository paths: **CMS** = `K:\Development\Projects\SlpModularCms`, **WEB** = this repo.
## U1 `core-site-hosting` (CMS repo, built by the CMS session)
- **Purpose**: Teach the shared host to serve a prerendered website the way nginx does today, and give such a site a strict CSP, without changing any existing host.
- **Components**: C2 `CmsHostOptions.WebsiteMode`, C3 prerendered site serving (resolver, middleware, cache policy, indexing policy, compression), C4 `StrictSite` policy.
- **Requirements**: FR-3, FR-8, FR-9, FR-10 (policy part), NFR-2, NFR-3, NFR-4, NFR-6 (resolver and policy tests), NFR-8 (CMS docs).
- **Construction stages**: Functional Design, NFR Requirements, NFR Design, Infrastructure Design (only if the host change touches deployment; expected none), Code Generation.
- **Done when**: unit and property-based tests pass; `Api` and `Api.SlpSoftware` behave unchanged (their tests green); `WEBSITE_WORKSPACE.md` and README describe the mode; the hand-back note is written. **Checkpoint**: the CMS session reports back after U1 before starting U2.
- **Code location**: `src/SlpModularCms.Core/Hosting` (and `.../Security`) plus `src/SlpModularCms.Core.Tests`.
## U2 `andreaslop-client` (CMS repo, built by the CMS session)
- **Purpose**: Andrea's own host with a themed Dutch admin, deployed to test through the CMS CI/CD.
- **Components**: C1 `SlpModularCms.Api.AndreaSlopFotografie` (project, appsettings, database, dev port, module references without `Offerings`, `WebsiteMode = PrerenderedPages`, `SecurityHeaders` and `Website` configuration), C5 admin theme `themes/andreaslop/` and `VITE_THEME`/`VITE_DEFAULT_LANGUAGE`, C6 CMS CI/CD (per-client admin build, publish, deploy, `wwwroot/web/` kept outside the swapped release).
- **Requirements**: FR-1, FR-2, FR-4, FR-5, FR-6, FR-7, FR-10 (configuration part), FR-11, NFR-1 (setup flow exposure, logging), NFR-5, NFR-6 (client tests), NFR-7.
- **Construction stages**: Functional Design (module minimum, setup flow), NFR Requirements, NFR Design, Infrastructure Design (database for the new host, ports, release layout, CI matrix), Code Generation.
- **Done when**: the host starts on test with its own database, `/admin` shows Andrea's theme in Dutch and allows first-admin setup and login, `/api/v1/System/capabilities` lists no `Offerings`, `/health` is green, and `Api.SlpSoftware` still builds and deploys unchanged.
- **Code location**: `src/SlpModularCms.Api.AndreaSlopFotografie`, `frontend/themes/andreaslop`, `.gitea/workflows`, solution placement under **Clients** per the CMS repo's `AGENTS.md`.
## U3 `site-delivery` (WEB repo, built by this session)
- **Purpose**: Get the prerendered site onto Andrea's host and prove it behaves like the old static deployment.
- **Components**: C7 delivery job in the web CI, C8 extended `web/deploy/verify-deployment.sh` (exact CSP, canonical redirects, `404.html` status, cache and `noindex` on test, admin and API reachable), retiring the static nginx test site after proof.
- **Requirements**: FR-12, FR-13, FR-14, FR-10 (drift guard), NFR-2, NFR-3 (Lighthouse not lower), NFR-5.
- **Construction stages**: Infrastructure Design, Code Generation. (Functional Design, NFR Requirements and NFR Design are skipped as planned.)
- **Done when**: a web CI run on the target branch delivers the build to the test host; verification passes; the static test site is retired.
- **Code location**: this repo's CI workflow and `web/deploy/`. No change to `web/src`. Starts after the Testimonials feature has merged or overlap is ruled out.
## Cross-cutting
- **FR-15** (collaboration with the CMS session) spans all units. One brief covers U1 and U2 (owner decision); the CMS session sequences them and reports back after U1. The brief lives in this feature's folder and a copy is placed in the CMS repo's AIDLC folder.
- **Build and Test** (phase level) covers the proof across all three units on test.
- **Operations** (Deployment, Monitoring, Production Readiness) covers the new host on test.
- **Code organisation**: brownfield; no new top-level directories in this repo. Documentation only under `aidlc-docs/features/cms-api-foundation/`; the CMS session records its approved design and hand-back under `construction/cms-host/` here.
@@ -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)
@@ -0,0 +1,148 @@
# Vragen bij de requirements: cms-api-foundation
Vul achter elke `[Answer]:` de letter van je keuze in. Past geen enkele optie, kies dan de laatste (Anders) en licht je keuze toe. Bij elke vraag staat welke optie ik aanbeveel en waarom.
**Wat deze feature is:** de basis waarop Andrea's site straks op de SlpModularCms draait. Dus: een eigen client-project voor Andrea (zoals `Api.SlpSoftware`), een vast thema per site, een instelbare set modules per site, en de CMS-host die zowel de admin als de geprerenderde site serveert. Pakketten, contactformulier, testimonials en shoot-pagina's zijn aparte, latere features.
**Vaste uitgangspunten, hierover hoef je niets te beslissen** (uit je antwoorden):
- Meerdere sites = één deployment en één database per site; de modules per site bepaal je met de DLL-referenties van de client (aangepast in het ontwerp).
- Het thema staat vast per site en wordt niet in de admin aangepast.
- De CMS-host serveert admin (`/admin`), API (`/api/v1`) en de site (`/`); er is maar ruimte voor één website op de host.
- Dit werk raakt de bestanden van de Testimonials-sessie niet.
## Vraag 1
Wat hoort er in deze feature bij het "de CMS serveert de site" deel aan de kant van deze (web)repo?
- A) Alleen de CMS-kant: een brief en bewaking van het resultaat. De omschakeling van de huidige hosting (nginx test, IIS productie) en de CI van de site volgt in een eigen feature.
- B) CMS-kant én de web-kant: de site-build wordt bij de deploy in `wwwroot/web/` van de CMS-host gezet, de CI van de web-repo wordt daarop aangepast en op test is de omschakeling bewezen. Aanbevolen: de feature is pas af als de keten werkt, en de web-kant is klein.
- C) CMS-kant plus web-kant tot en met productie.
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: B
## Vraag 2
Hoe moet de CMS-host de geprerenderde pagina's serveren? Nu is er een SPA-fallback: een pad zonder extensie (`/over-mij`) krijgt `index.html`. Onze build maakt per pagina een eigen HTML-bestand, en een onbekend pad moet de echte 404-pagina met status 404 krijgen.
- A) De host krijgt een "geprerenderde site"-modus: eerst `{pad}.html` of `{pad}/index.html`, anders de 404-pagina met status 404. Aanbevolen: dit geeft de bezoeker de snelle HTML en de SEO-winst van de prerendering echt.
- B) De bestaande SPA-fallback blijft: elke pagina laadt `index.html` en React rendert daarna. Dan verdwijnt het voordeel van de prerendering.
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A (prerender-modus nu). User note: wants SSR eventually to be independent of the build pipeline; asked whether Node runs on mijnhostingpartner.nl (unknown, to be checked by the user). Decision: prerender-modus now, SSR vs hybrid decided before the first content feature.
## Vraag 3
De site heeft nu strenge beveiligingsheaders (CSP uit `web/config/securityHeaders.ts`). De CMS geeft de site standaard het mildere `Relaxed`-beleid.
- A) De CMS-host krijgt een instelling waarmee het client-project de CSP voor `/` zelf kan bepalen, en Andrea's client gebruikt dezelfde strenge CSP als nu. Aanbevolen: geen beveiligingsachteruitgang bij de omschakeling.
- B) We accepteren het `Relaxed`-beleid voor de site.
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 4
Hoe wordt het thema per site vastgelegd?
- A) In het client-project (configuratie of een vast bestand), dat de API aanbiedt; de admin leest het bij het opstarten en zet het als CSS-variabelen. Eén admin-build voor alle sites. Aanbevolen.
- B) Een aparte admin-build per site met het thema ingebakken.
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: X: admin build per site where only a theme file is specified (user proposal; styling does not belong in the API). Theme files live in the CMS repo, selected at build time, no theme API.
## Vraag 5
Wat moet het thema per site kunnen bepalen?
- A) Kleuren (de bestaande tokens), hoekafronding, lettertype, logo/app-naam en favicon. Aanbevolen: genoeg om aan te sluiten op Andrea's site, zonder overbodige vrijheid.
- B) Alleen kleuren en logo/app-naam.
- C) Alles uit A plus eigen CSS per site.
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 6
Welke modules staan voor Andrea aan in deze feature? (Master is voor het beheren van andere CMS-instanties; Availability hoort bij de master-status.)
- A) Alleen wat voor een werkende admin nodig is (Identity en wat de CMS-host verplicht stelt); `Offerings` staat uit. Zo bewijst het verschil met SlpSoftware dat de schakelaar werkt. Aanbevolen.
- B) Identity plus `Offerings` aan, zodat de pakketten-feature er direct op kan aansluiten.
- C) Alles aan, net als de bestaande Api-host.
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A (this feature = step 0; Offerings is switched on in the packages feature)
## Vraag 7
Wie zijn de gebruikers van Andrea's CMS in deze feature?
- A) Zoals nu: een eerste beheerder via de setup-flow en daarna uitnodigingen. Geen nieuwe rollen. Aanbevolen: auth bestaat al en hoeft hier niet opnieuw ontworpen.
- B) Er komen rollen bij (bijvoorbeeld beheerder en alleen-lezen).
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 8
Welke taal heeft de admin standaard voor Andrea? De admin kent NL en EN.
- A) Nederlands standaard, Engels blijft kiesbaar; de standaardtaal wordt per site vastgelegd. Aanbevolen.
- B) Engels standaard, zoals nu.
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 9
Op welke omgevingen komt Andrea's CMS-instantie in deze feature?
- A) Eerst alleen test (de Pi, via de bestaande Gitea-deploy van de CMS-repo); productie volgt als de keten bewezen is. Aanbevolen.
- B) Test en productie.
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 10
Hoe werk ik met de CMS-sessie (`AndreaSlopFotografie`) samen?
- A) Hybride: web-vragen beantwoord ik zelf uit de repo en het design. Beslissingen over CMS-interne zaken, security en datamodel leg ik aan jou voor. Jij keurt de requirements en het ontwerp van de CMS-kant goed. Aanbevolen.
- B) Ik beantwoord alles wat ik uit de context kan afleiden, houd een besluitenlijst bij en jij keurt alleen het eindresultaat goed.
- C) Alle vragen van de CMS-sessie gaan naar jou.
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 11: Beveiligingsextensies
Moeten de beveiligingsregels als harde vereisten worden afgedwongen voor dit project?
- A) Ja: dwing alle BEVEILIGINGSREGELS af als blokkerende vereisten (aanbevolen voor productietoepassingen)
- B) Nee: sla alle BEVEILIGINGSREGELS over (geschikt voor PoC's, prototypes en experimentele projecten)
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 12: Property-Based Testing Extensie
Moeten de property-based testing (PBT) regels worden afgedwongen voor dit project?
- A) Ja: dwing alle PBT-regels af als blokkerende vereisten (aanbevolen voor projecten met bedrijfslogica, datatransformaties, serialisatie of stateful componenten)
- B) Gedeeltelijk: dwing PBT-regels alleen af voor pure functies en serialisatie round-trips (geschikt voor projecten met beperkte algoritmische complexiteit)
- C) Nee: sla alle PBT-regels over (geschikt voor eenvoudige CRUD-applicaties, UI-only projecten of dunne integratielagen zonder significante bedrijfslogica)
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: B
## Vraag 13: Operations-fase
Moet deze feature na de Construction-fase door de Operations-fase (deployment en monitoring inrichten)?
- A) Ja: voer de Operations-fase uit na Construction (deployment en monitoring)
- B) Nee: stop na Build and Test (deployment en monitoring vallen buiten deze feature)
- C) Nog niet zeker: vraag het me opnieuw na de Construction-fase
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
@@ -0,0 +1,97 @@
# Requirements: cms-api-foundation ("step 0")
## Intent analysis
- **User request**: Start the API and CMS for the Andrea Slop Fotografie website on top of the owner's existing modular CMS (`SlpModularCms`, separate repo), feature by feature. This feature is **step 0**: a working CMS plus API host for the site, with per-site theming and a per-site module set (chosen by the DLLs the client references), serving both the admin and the prerendered website from one host. Packages, contact form, testimonials and shoot pages are later features.
- **Request type**: New feature (cross-repo): extension of an existing system.
- **Scope estimate**: Cross-system. CMS repo (new client host, shared host composition, admin frontend theming, CI) and this web repo (deploy pipeline, site build output).
- **Complexity estimate**: Complex. Hosting model change, security headers, shared-host change that must not regress the existing SlpSoftware client.
- **Requirements depth**: Comprehensive. Security-relevant (CSP, auth host), two repos, two AIDLC workspaces.
- **Clarity**: Clear after the 13 clarification questions (answers in `requirement-verification-questions.md`).
## Context (verified by reading the CMS repo, read-only)
- SlpModularCms is a .NET 10 modular monolith on MariaDB. Modules: `Identity` (login, refresh, revoke, invitations, setup, users), `Master`, `Availability`, `Offerings`. Admin: Vite + React 19 + TypeScript + Tailwind v4 (primary `#ac0000`) + shadcn-style components, NL/EN.
- Multi-site pattern today: one deployable client project per site (`Api.SlpSoftware`), a thin `Program.cs` over the shared `CmsHost` composition in `SlpModularCms.Core`, with its own database.
- Single-host serving: one process serves `/` (site from `wwwroot/web/`), `/admin`, `/api/v1`. Reserved paths: `/admin`, `/api/v1`, `/health`. Extensionless paths currently fall back to `wwwroot/web/index.html`. The site gets the `Relaxed` CSP, the reserved paths `Strict`.
- No theming exists; only CSS variables in the admin `index.css`.
- This web repo: a prerendered React SPA (one HTML file per page), currently deployed as static files behind nginx (test) and IIS (production), with a strict CSP from `web/config/securityHeaders.ts`.
## Decisions taken in clarification
| # | Decision |
|---|---|
| Q1 | Scope covers the CMS side and the web side, proven on **test**. |
| Q2 | The host gets a prerendered-site mode now. SSR (the owner wants it eventually, to be independent of the build pipeline) versus a hybrid (CMS blocks loaded at runtime) is decided before the first content feature. The owner checks whether the hosting partner allows a Node process. |
| Q3 | The client project determines the CSP for `/`; Andrea's client uses the same strict CSP as the site has today. |
| Q4 | Admin is built per site; a per-site theme file is selected at build time. No theme in the API. |
| Q5 | The theme covers colours (existing tokens), radius, font, logo/app name and favicon. |
| Q6 | `Offerings` is **off** for Andrea in step 0; it is switched on in the packages feature. |
| Q7 | Users as today: first admin through the setup flow, then invitations; no new roles. |
| Q8 | Admin default language per site; Dutch for Andrea, English remains selectable. |
| Q9 | Only the test environment in step 0. |
| Q10 | Hybrid collaboration with the CMS session (see Process requirements). |
| Q11 | Security Baseline extension enforced. |
| Q12 | Property-based testing: partial (PBT-02, 03, 07, 08, 09). |
| Q13 | Operations phase included. |
## Functional requirements
### Client host (CMS repo)
- **FR-1** A new client project `SlpModularCms.Api.AndreaSlopFotografie` exists in the CMS repo, following the `Api.SlpSoftware` pattern: a thin `Program.cs` on the shared `CmsHost`, its own database, its own local dev port, the three-file appsettings pattern, and solution placement per the CMS repo's `AGENTS.md`.
- **FR-2** The active module set of a site is the set of module projects its client host references (the existing mechanism: a module DLL that ships with the host is a module that is on). Andrea's client references only the modules the admin needs and not `Offerings`; a module that is not referenced registers nothing (no controllers or routes, no database context or migrations, no admin navigation entry) and `/api/v1/System/capabilities` lists only the referenced modules. Switching a module on later means adding its reference to the client project. No configuration filter is added to the shared host (owner decision, design stage, 2026-11-06, which supersedes the earlier "configuration switch per module" assumption).
- **FR-3** Existing hosts (`Api`, `Api.SlpSoftware`) keep their current behaviour: same modules, same endpoints, same look, same tests passing.
### Theming (CMS repo, admin frontend)
- **FR-4** A theme is a per-site theme file (CSS tokens: colours, radius, font) plus logo, app name and favicon, stored in the CMS repo and selected when the admin is built. Without a selection, the admin keeps today's look.
- **FR-5** The CI builds the admin once per deployable client with that client's theme. The API exposes no theme.
- **FR-6** Andrea's theme matches the site's visual identity (source: this repo's design reference `design/andreaslop-static/` and the web theme).
- **FR-7** The default admin language is configurable per site; Andrea's default is Dutch.
### Serving the site (CMS repo, shared host)
- **FR-8** The host has a prerendered-site mode: for a request path without a file extension it serves `{path}.html`, else `{path}/index.html`; for an unknown path it serves the site's 404 page with HTTP status 404. URLs have no trailing slash, query strings are preserved, and the reserved paths `/admin`, `/api/v1` and `/health` always win.
- **FR-9** Existing behaviour (SPA fallback) remains available for sites that do not use the prerendered mode, so SlpSoftware is unaffected.
- **FR-10** The CSP (and the other security headers) for `/` is set per client project. Andrea's client reproduces the strict policy of `web/config/securityHeaders.ts`. A mechanism keeps the two from drifting apart (decided in design).
### Authentication
- **FR-11** Authentication is the existing Identity module, unchanged: first administrator via the setup flow, then invitations, no new roles. For Andrea's instance the setup flow must not be reachable by anyone else once the first administrator exists.
### Web repo (this repo)
- **FR-12** The site build output (prerendered pages, assets, 404 page) can be delivered to `wwwroot/web/` of Andrea's CMS host on test as part of the deploy, without a manual step.
- **FR-13** The web CI is adapted for that delivery. Removing the static nginx deployment of the test site is part of the switch, but only after the new route works.
- **FR-14** Proof on test: the home page and at least one sub page are served prerendered, an unknown path returns the 404 page with status 404, `/admin` shows Andrea's theme and allows login, `/health` and `/api/v1/System/capabilities` respond and show `Offerings` off.
### Process
- **FR-15** The CMS work is handed to the CMS session (`AndreaSlopFotografie`, `dbb9e4`) as a feature brief per feature; the CMS session runs its own AIDLC. This session answers web-side questions; CMS-internal, security and data-model decisions go to the owner, who approves the CMS requirements and design. The result is handed back as an artifact (changed contract and changelog) which this session verifies by integrating it.
## Non-functional requirements
- **NFR-1 Security (Security Baseline enforced).** Applicable rules for step 0: SECURITY-03 (structured logging, no secrets in logs), SECURITY-04 (security headers on all HTML endpoints; no `unsafe-inline` or `unsafe-eval` without documented justification), SECURITY-05 (input validation, existing endpoints), SECURITY-08 (deny by default, CORS only for allowed origins, server-side token validation), SECURITY-09 (no default credentials, generic production errors, no directory listing, no sample content), SECURITY-10 (lock files, vulnerability scan step, pinned CI versions), SECURITY-11 (rate limiting on login, misuse case for the setup flow), SECURITY-12 (credential and session handling as existing; no committed secrets), SECURITY-13 (build integrity), SECURITY-15 (global error handler, fail closed). SECURITY-01, 02, 06, 07 and 14 are assessed per stage (database TLS and encryption at rest, access logging on the reverse proxy, least privilege of the deploy identity, network exposure of the Pi, alerting). Non-compliance is a blocking finding.
- **NFR-2 No security regression.** Moving the site behind the CMS host must not weaken the headers the site has today (see FR-10).
- **NFR-3 Performance.** Prerendered pages are served as static files with compression and long-lived caching for hashed assets, and the site's Lighthouse targets (see the open follow-ups) must not drop compared to the nginx deployment.
- **NFR-4 Compatibility.** Existing hosts and tests keep working (FR-3); the shared `CmsHost` change is backward compatible by default.
- **NFR-5 Deployability.** Runs on the test Pi (ARM64, MariaDB) through the existing Gitea CI/CD with its atomic release switch. `wwwroot/web/` stays outside the swapped release directory so a CMS deploy does not remove the site.
- **NFR-6 Testing.** Unit and integration tests for module composition (a client without a module exposes none of its routes), prerendered-site serving (including 404 status and reserved paths) and header configuration. Property-based tests (partial mode, PBT-02, 03, 07, 08, 09) for pure functions and round-trips, for example path-to-file resolution and configuration parsing.
- **NFR-7 Maintainability.** Per-site differences live in the client project and the theme file; the shared host contains no site names.
- **NFR-8 Documentation.** CMS repo docs (`WEBSITE_WORKSPACE.md`, README) are updated for the prerendered mode, module composition per client and themes.
## Out of scope for step 0
Offerings/packages, contact form, testimonials, shoot pages and media upload; SSR or the hybrid runtime content loading (decided before the first content feature); production cutover and the IIS hosting; the `Master` module for Andrea; roles; a theme editor in the admin; changes to files owned by the Testimonials session.
## Open items and risks
- **Hosting partner**: whether a Node process (SSR) is possible on `mijnhostingpartner.nl`, and whether the production host runs .NET, is unknown. The owner checks this; it does not block step 0.
- **CSP source of truth**: the site's policy lives in `web/config/securityHeaders.ts`. How the CMS client project gets the same values without drifting (generated artifact, shared file, or test that compares) is a design decision.
- **Parallel work**: the Testimonials session edits `aidlc-docs/active-features.md` (row-level merge conflict expected) and web components. This feature touches `web/` only for the deploy pipeline, and only after the Testimonials feature has merged or confirmed no overlap.
- **Dev ports and databases**: Andrea's client needs its own dev port and local database, as `Api.SlpSoftware` has.
## Direction note (owner, 2026-11-06, tracked by the website session)
More and more of the website will become dynamic (CMS-driven), so the share of purely prerendered, static serving is expected to shrink over time. This is not a change to step 0: the prerendered-site mode stays as designed. It is an input to the decision on SSR versus a hybrid (CMS blocks loaded at runtime), which must be taken before the first content feature (packages), together with the answer to whether the hosting partner allows a Node process. Design consequence to keep in mind: the host's prerendered mode and its nginx-parity rules must stay usable next to dynamic content (for example as the fallback for pages that are not CMS-driven).