Files
AndreaSlopFotografie/aidlc-docs/features/cms-api-foundation/construction/cms-host/brief-u1-u2.md
T
SluijsensandClaude Sonnet 5.5 288b0e3838
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
Adds the AI-DLC documents of the CMS and API foundation feature
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-08 02:06:00 +01:00

11 KiB

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 <name>.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):

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.