Files
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

4.8 KiB

Application Design: cms-api-foundation (consolidated)

Details: components.md, component-methods.md, services.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).