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), featurecms-api-foundation - To: the CMS session
AndreaSlopFotografie[dbb9e4], repoSlpModularCms - 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 ataidlc-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 hostSlpModularCms.Api.AndreaSlopFotografiewith 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)
- 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.
Offeringsis not referenced by Andrea's client; adding the reference later switches it on. - 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.
- The host serves
/admin,/api/v1and the website (/) from one process; the production host has room for only one website. - Test environment only in this feature. Production, the
Mastermodule for Andrea, extra roles, SSR and CMS-driven site content are out of scope. - Authentication is the existing Identity module unchanged (first admin via setup flow, then invitations).
- The admin's default language for Andrea is Dutch; English stays selectable.
- 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.DiscoverModulesloadsSlpModularCms.Modules.*.dllnext to the host; the client.csprojreferences decide the module set.CmsHostOptionsis empty and documented as the extension point for per-client differences; it is passed to bothCmsHost.ConfigureServicesandConfigurePipeline.StaticContentExtensionsmountswwwroot/webat/withUseDefaultFilesand an extensionless fallback toindex.html. It does not map/over-mijtoover-mij.htmland does not serve a 404 page with status 404. The current fallback also answers unknown paths under/api/v1with the websiteindex.html; the new mode must not.SecurityHeadersOptions.PathPoliciesplus the code-definedCspPolicyCatalog(Strict,Relaxed).Strictdeliberately takes no extra script origins.- Admin build already reads
VITE_APP_TITLE,VITE_API_BASE_URL; CI is.gitea/workflows/continuous_integration.yamlanddeploy-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, soApiandApi.SlpSoftwareare unchanged) andPrerenderedPages. - 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.
/servesindex.html;/xservesx.html(alsox/index.htmlif 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.htmlwith status 404, neverindex.html; plain 404 if404.htmlis missing. - Reserved prefixes
/admin,/api/v1,/healthare never handled by this middleware; an unknown API path stays an API 404. - Cache-Control: pages
no-cache; hashed files under/assetslong-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, nofollowon website responses and/robots.txtanswersUser-agent: */Disallow: /.
- 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.
- C4
StrictSitepolicy inCspPolicyCatalog: theStrictdirectives plus configured script origins inscript-srcand configured connect origins inconnect-src;X-Frame-Options: DENY;frame-ancestors 'none'.StrictandRelaxeddo not change. The new name is accepted byPathPolicyRulevalidation; unknown names still fail startup. Confirm HSTS,X-Content-Type-OptionsandReferrer-Policyare 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.mdand 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): thinProgram.csonCmsHost,WebsiteMode = PrerenderedPages, three-file appsettings, own database, own dev port,SecurityHeaders:DefaultPolicy = StrictSitewith the Umami and Sentry origins above,Website:NoIndex = truefor 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_THEMEselects it at build time (unset = today's look); newVITE_DEFAULT_LANGUAGE(nlfor Andrea). Andrea's site identity (palette fromweb/src/theme.ts, sourcedesign/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.pngand faviconweb/public/favicon.pngin 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_LANGUAGEandVITE_APP_TITLE; publish the new host; deploy to the test host with the existing atomic release switch; keepwwwroot/web/outside the swapped release directory so the website survives every CMS deploy. Do not touch the production path forApi.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:
- What was built (components, files) and anything that deviates from this brief, with the reason.
- Test results: unit, property-based (with the seed handling you used), and the
Api/Api.SlpSoftwareregression run. - Configuration values the website repo must know (header values, origins, hostnames, delivery path, ports).
- Open questions or risks.
I verify the hand-back by integrating it in the website repo (unit U3) and by the deployment checks there.