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.