Files
AndreaSlopFotografie/aidlc-docs/features/cms-api-foundation/inception/plans/application-design-plan.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

7.1 KiB

Application Design Plan: cms-api-foundation

Depth: minimal-to-standard, contract level. Detailed business rules are for Functional Design (U1, by the CMS session).

What the code reading showed (inputs to the design)

  • Module discovery (ModuleOrchestrator.DiscoverModules) loads every SlpModularCms.Modules.*.dll found next to the host and instantiates each IModule. So today "which modules" = which projects the client .csproj references. There is no config filter yet. MVC controller discovery is a separate mechanism and must be filtered too, or a disabled module's routes can still answer.
  • CmsHostOptions is an empty class, documented as the extension point for per-client differences, passed to both CmsHost.ConfigureServices and ConfigurePipeline.
  • Static content (StaticContentExtensions) mounts wwwroot/web at / with UseDefaultFiles plus an extensionless SPA fallback to index.html. It does not map /over-mij to over-mij.html and does not serve 404.html with status 404.
  • Security headers are already per path: SecurityHeadersOptions.PathPolicies (first match wins) plus a code-defined CspPolicyCatalog with exactly two policies, Strict and Relaxed. Strict never gets extra script origins ("the admin SPA must not load script from anywhere but itself").
  • The site's CSP (web/config/securityHeaders.ts) is Strict-like but needs the Umami script origin in script-src and the Umami and Sentry ingest origins in connect-src. So neither existing catalog policy matches it.
  • The site's build (TanStack Start prerender) writes over-mij.html, 404.html and index.html without folders, and externalizes inline scripts so the strict CSP works.
  • The site's current nginx/IIS config (generated by web/config/serverConfig.ts, rules BR-HST-01 to 11) does more than serve files: canonical-URL 301 redirects (uppercase, .html, trailing slash), 404.html with status 404, the header set, Cache-Control: no-cache for pages and long caching for hashed /assets, gzip for text types, and on test X-Robots-Tag: noindex plus a robots.txt that disallows everything. The CMS host has to take over what matters of this.
  • Admin build already takes build-time variables (VITE_APP_TITLE, VITE_API_BASE_URL), so a per-site theme selector (VITE_THEME) fits the existing approach.
  • CI/CD in the CMS repo: .gitea/workflows/continuous_integration.yaml and deploy-scp.yaml.

Plan

  • Analyze requirements and read the CMS host code (read-only)
  • Collect answers to the design questions below
  • Analyze answers for ambiguity; ask follow-ups if needed (none: Q1 clarified in chat and applied to FR-2)
  • Generate application-design/components.md
  • Generate application-design/component-methods.md
  • Generate application-design/services.md
  • Generate application-design/component-dependency.md
  • Generate application-design/application-design.md (consolidated)
  • Validate design completeness and consistency (including Security Baseline check)

Design questions

Question 1: Module switch

How does a client choose its modules?

  • A) Every client references all module projects; an allowlist in configuration (Modules:Enabled) decides which are active. The orchestrator skips the others and a controller filter removes their routes. Hosts without the setting behave as today (everything discovered is active). Enabling a module later is a config change. Recommended: matches the decision "configuration switch per module".
  • B) Each client references only the modules it needs (what happens now). No new filter code, and unused module code is not on disk, but enabling a module later needs a code change and a new build.
  • X) Other (describe after the Answer: tag below)

Question 2: How the site's CSP is realised

  • A) A third, code-defined policy in CspPolicyCatalog (working name StrictSite): the Strict directives plus the configured script and connect origins. Strict for the admin stays untouched. Recommended: keeps "code decides what a policy means" and does not loosen the admin.
  • B) Let Strict accept the extra script origins. Fewer lines, but it weakens the admin's policy for every client.
  • X) Other (describe after the Answer: tag below)

Question 3: Keeping the two CSP definitions from drifting

The site's CSP lives in the web repo, the host's in the CMS repo.

  • A) The web repo's existing deployment check (web/deploy/verify-deployment.sh) asserts that the deployed host sends exactly contentSecurityPolicy('production') from securityHeaders.ts. Drift fails the web deploy. Recommended: one extra assertion, no cross-repo coupling.
  • B) The site build emits a manifest with its CSP, which the host reads at startup. No drift, but the site (not CMS code) then decides its own policy, which goes against the CMS's code-defined policy design.
  • C) Document it only.
  • X) Other (describe after the Answer: tag below)

Question 4: How much of nginx's behaviour does the host take over

  • A) Parity for what the site relies on: canonical-URL 301 redirects, 404.html with status 404, Cache-Control (pages no-cache, /assets long), compression of text types, and on test X-Robots-Tag: noindex with a disallow-all robots.txt (configured per environment, so production does not get it). Recommended: otherwise the switch changes SEO behaviour and the test site could get indexed.
  • B) Minimal: serve the files, 404.html with status 404 and the security headers. Redirects, caching and compression follow before production.
  • X) Other (describe after the Answer: tag below)

Question 5: Where per-client behaviour is configured

  • A) The serving mode (prerendered pages versus SPA fallback) is a property of CmsHostOptions, set in the client's Program.cs (a property of the client's code). Environment-dependent things (noindex on test, allowed origins, enabled modules) go in appsettings. Recommended.
  • B) Everything in appsettings, including the serving mode.
  • X) Other (describe after the Answer: tag below)

Question 6: How a theme is applied to the admin

  • A) A theme is a folder in the CMS frontend/ (for example themes/andreaslop/) with a CSS file that overrides the existing tokens, plus logo and favicon. VITE_THEME selects it at build time; without it the default look stays. Recommended: smallest change to the current index.css tokens.
  • B) The theme is a JSON file with tokens that a build step turns into CSS.
  • X) Other (describe after the Answer: tag below)

Question 7: How the brief reaches the CMS session

  • A) The brief stays in this repo's AIDLC folder (single source). I message the CMS session the path and it reads it; the CMS session decides what to copy into its own AIDLC workspace. Recommended: no writes into the CMS repo's AIDLC files from here.
  • B) I place a copy of the brief in the CMS repo's AIDLC folder.
  • X) Other (describe after the Answer: tag below)