# Feature brief for the CMS session: Andrea's site on SlpModularCms (units U1 and U2) - **From**: session "CMS & API" [fc4f23], repo `AndreaSlopFotografie` (the website repo), feature `cms-api-foundation` - **To**: the CMS session `AndreaSlopFotografie` [dbb9e4], repo `SlpModularCms` - **Date**: 2026-11-06 - **Source of truth**: `K:\Development\SlpSoftware\Projects\AndreaSlopFotografie-cms-api-foundation\aidlc-docs\features\cms-api-foundation\` (requirements, application design and unit documents are there; this brief summarises them). A copy of this brief sits in your repo at `aidlc-docs/_shared/handoffs/`; move it wherever your AIDLC prefers. ## 1. What we ask Run your own AIDLC workflow for **one feature that contains two units**, and hand back after each unit. Suggested slug: `andreaslop-site-hosting`. - **U1 `core-site-hosting`**: 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. - **U2 `andreaslop-client`**: add the client host `SlpModularCms.Api.AndreaSlopFotografie` with a themed Dutch admin and CI/CD to the test host. **Checkpoint**: report back to me after U1 (hand-back note, section 7) and wait for my "go" before U2. The owner (Bryan) approves your requirements and your design for this feature; do not skip those approval gates. ## 2. Decisions already taken by the owner (do not re-ask) 1. One deployment and one database per site. A site's modules are the **module projects its client references** (the existing DLL discovery). **No configuration filter** is added to the shared host. `Offerings` is not referenced by Andrea's client; adding the reference later switches it on. 2. The theme is fixed per site, never edited in the admin, and not served by the API. Admin is **built per site** with a theme selected at build time. 3. The host serves `/admin`, `/api/v1` and the website (`/`) from one process; the production host has room for only one website. 4. Test environment only in this feature. Production, the `Master` module for Andrea, extra roles, SSR and CMS-driven site content are out of scope. 5. Authentication is the existing Identity module unchanged (first admin via setup flow, then invitations). 6. The admin's default language for Andrea is Dutch; English stays selectable. 7. Extensions the owner enabled for this work (your own AIDLC will ask its own opt-in questions: forward them to me, the owner decides): Security Baseline enforced; property-based testing in partial mode (PBT-02, 03, 07, 08, 09). ## 3. Facts from your code that the design builds on (verified read-only) - `ModuleOrchestrator.DiscoverModules` loads `SlpModularCms.Modules.*.dll` next to the host; the client `.csproj` references decide the module set. - `CmsHostOptions` is empty and documented as the extension point for per-client differences; it is passed to both `CmsHost.ConfigureServices` and `ConfigurePipeline`. - `StaticContentExtensions` mounts `wwwroot/web` at `/` with `UseDefaultFiles` and an extensionless fallback to `index.html`. It does not map `/over-mij` to `over-mij.html` and does not serve a 404 page with status 404. The current fallback also answers unknown paths under `/api/v1` with the website `index.html`; the new mode must not. - `SecurityHeadersOptions.PathPolicies` plus the code-defined `CspPolicyCatalog` (`Strict`, `Relaxed`). `Strict` deliberately takes no extra script origins. - Admin build already reads `VITE_APP_TITLE`, `VITE_API_BASE_URL`; CI is `.gitea/workflows/continuous_integration.yaml` and `deploy-scp.yaml`. ## 4. U1 `core-site-hosting`: required behaviour Components (names are indicative; responsibilities and interfaces are the contract): - **C2 `CmsHostOptions.WebsiteMode`**: `SpaFallback` (default, current behaviour, so `Api` and `Api.SlpSoftware` are unchanged) and `PrerenderedPages`. - **C3 prerendered site serving**, active only in `PrerenderedPages`: - **Path resolution** as a pure function with a file-exists predicate, total (never throws, never leaves the website root, rejects traversal), returning serve-file, redirect-to-canonical or not-found. `/` serves `index.html`; `/x` serves `x.html` (also `x/index.html` if present). Canonical form: lowercase, no `.html`, no trailing slash, query string preserved; other spellings get a 301. Paths that look like files are served as files or 404. - **Unknown path**: serve `404.html` with **status 404**, never `index.html`; plain 404 if `404.html` is missing. - **Reserved prefixes** `/admin`, `/api/v1`, `/health` are never handled by this middleware; an unknown API path stays an API 404. - **Cache-Control**: pages `no-cache`; hashed files under `/assets` long-lived and immutable. - **Compression** of text types using built-in response compression (no new dependency). - **Indexing policy**: setting `Website:NoIndex` (default false). When true: `X-Robots-Tag: noindex, nofollow` on website responses and `/robots.txt` answers `User-agent: *` / `Disallow: /`. - **C4 `StrictSite` policy** in `CspPolicyCatalog`: the `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. The new name is accepted by `PathPolicyRule` validation; unknown names still fail startup. Confirm HSTS, `X-Content-Type-Options` and `Referrer-Policy` are emitted on website responses. - Pipeline order must stay as documented in `CmsHost` (security headers before static content). Compression sits before the website mount. The website 404 handling is last, after API routes. - Update `WEBSITE_WORKSPACE.md` and the README for the new mode. **Where the exact rules come from** (read these in the website repo, they are the behaviour to match): `web/config/canonicalUrls.ts`, `web/config/serverConfig.ts` (rules BR-HST-01 to 11), `web/config/compressibleTypes.ts`, `web/deploy/nginx/andreaslop-test.conf` (what test does today). **Site build output layout** (TanStack Start prerender, `autoSubfolderIndex: false`): `index.html`, one `.html` per page without folders, `404.html`, `assets/` with hashed names, plus sitemap and static files from `public/`. Inline scripts are externalised so the strict CSP works. **The CSP the site sends today** (must be reproduced exactly by `StrictSite` with the right origins): ```text default-src 'self'; script-src 'self' https://analytics.slpsoftware.nl; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self' https://analytics.slpsoftware.nl https://o4511795618185216.ingest.de.sentry.io; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none' ``` plus `Strict-Transport-Security: max-age=31536000; includeSubDomains`, `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin`. Note the current `Strict` also emits `frame-ancestors 'none'`, `base-uri`, `form-action` and `object-src`; check that the directive order and content can match the site's policy exactly. If an exact match is impossible, tell me before deciding: the website repo will assert the exact string (`web/deploy/verify-deployment.sh`, my unit U3) and can adapt its side. **Done when** (U1): unit and property-based tests pass (path resolution invariants: never escapes the root, canonical form is idempotent, no resolution of reserved prefixes; policy round trips), `Api` and `Api.SlpSoftware` tests are green and behave unchanged, docs updated, hand-back note written. ## 5. U2 `andreaslop-client`: required behaviour - **C1 project `SlpModularCms.Api.AndreaSlopFotografie`** (placed under **Clients** in the solution): thin `Program.cs` on `CmsHost`, `WebsiteMode = PrerenderedPages`, three-file appsettings, own database, own dev port, `SecurityHeaders:DefaultPolicy = StrictSite` with the Umami and Sentry origins above, `Website:NoIndex = true` for test. References only the modules the admin needs; find out the minimum (Identity, and whether Availability is required) and tell me what you found. - **C5 admin theme**: `frontend/themes/andreaslop/` with a CSS file overriding the existing tokens (colours, radius, font) plus logo and favicon; `VITE_THEME` selects it at build time (unset = today's look); new `VITE_DEFAULT_LANGUAGE` (`nl` for Andrea). Andrea's site identity (palette from `web/src/theme.ts`, source `design/andreaslop-static/` in the website repo): paper `#faf7f2`, paper-alt `#f1ebe2`, paper-deep `#e8e0d5`; ink `#232120`, ink-soft `#55504b`, ink-muted `#8a827a`; line `#e2dad0`; accent (heidegroen) `#7f8b76`, accent-deep `#5f6a58` (use for text and buttons: white on it meets 4.5:1), accent-deeper `#475042`; sand `#d9cdbc`; error `#a4443a`. Fonts: Marcellus for headings, Jost for body, with the same fallbacks as the site. Logo: `web/public/logo.png` and favicon `web/public/favicon.png` in the website repo. Keep contrast accessible (the admin's destructive and ring colours must stay readable on the paper background). - **C6 CMS CI/CD**: build the admin per deployable client with its `VITE_THEME`, `VITE_DEFAULT_LANGUAGE` and `VITE_APP_TITLE`; publish the new host; deploy to the **test** host with the existing atomic release switch; keep `wwwroot/web/` outside the swapped release directory so the website survives every CMS deploy. Do not touch the production path for `Api.SlpSoftware`. - **Security**: the first-administrator setup flow on the new instance must not be usable by anyone else once the first administrator exists (assess and test); login rate limiting stays; no secrets in the repo (the three-file appsettings pattern). **Done when** (U2): the host starts on test with its own database; `/admin` shows Andrea's theme in Dutch and first-admin setup and login work; `/api/v1/System/capabilities` shows no `Offerings`; `/health` is green; `Api.SlpSoftware` still builds and deploys unchanged; hand-back note written. ## 6. How we work together - **Questions**: web-side questions (what the site needs, file layout, CSP, theme, design source) go to me via SendMessage to "CMS & API" [fc4f23]; I answer from the website repo and its AIDLC documents. CMS-internal choices, security trade-offs and data-model questions: ask the owner (Bryan) directly through your normal question files; I do not decide those. - **Approvals**: the owner approves your requirements and your design. Please tell me when those are approved so I can note it in `construction/cms-host/`. - **Boundaries**: do not change anything in the website repo. Do not touch production. Follow your repo's rules for commits, pushes and deploys; if you are unsure whether you may push or deploy to test, ask the owner. - **Parallel work**: another session is working on a testimonials feature in the website repo; it does not touch your repo. The testimonials will later become a CMS module, so keep module composition by DLL reference intact. ## 7. Hand-back note (after U1, and again after U2) A short markdown file in your AIDLC folder, and a message to me with its path, containing: 1. What was built (components, files) and anything that deviates from this brief, with the reason. 2. Test results: unit, property-based (with the seed handling you used), and the `Api`/`Api.SlpSoftware` regression run. 3. Configuration values the website repo must know (header values, origins, hostnames, delivery path, ports). 4. Open questions or risks. I verify the hand-back by integrating it in the website repo (unit U3) and by the deployment checks there.