7.1 KiB
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 everySlpModularCms.Modules.*.dllfound next to the host and instantiates eachIModule. So today "which modules" = which projects the client.csprojreferences. 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. CmsHostOptionsis an empty class, documented as the extension point for per-client differences, passed to bothCmsHost.ConfigureServicesandConfigurePipeline.- Static content (
StaticContentExtensions) mountswwwroot/webat/withUseDefaultFilesplus an extensionless SPA fallback toindex.html. It does not map/over-mijtoover-mij.htmland does not serve404.htmlwith status 404. - Security headers are already per path:
SecurityHeadersOptions.PathPolicies(first match wins) plus a code-definedCspPolicyCatalogwith exactly two policies,StrictandRelaxed.Strictnever gets extra script origins ("the admin SPA must not load script from anywhere but itself"). - The site's CSP (
web/config/securityHeaders.ts) isStrict-like but needs the Umami script origin inscript-srcand the Umami and Sentry ingest origins inconnect-src. So neither existing catalog policy matches it. - The site's build (TanStack Start prerender) writes
over-mij.html,404.htmlandindex.htmlwithout 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.htmlwith status 404, the header set,Cache-Control: no-cachefor pages and long caching for hashed/assets, gzip for text types, and on testX-Robots-Tag: noindexplus arobots.txtthat 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.yamlanddeploy-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 nameStrictSite): theStrictdirectives plus the configured script and connect origins.Strictfor the admin stays untouched. Recommended: keeps "code decides what a policy means" and does not loosen the admin. - B) Let
Strictaccept 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 exactlycontentSecurityPolicy('production')fromsecurityHeaders.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.htmlwith status 404,Cache-Control(pages no-cache,/assetslong), compression of text types, and on testX-Robots-Tag: noindexwith a disallow-allrobots.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.htmlwith 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'sProgram.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 examplethemes/andreaslop/) with a CSS file that overrides the existing tokens, plus logo and favicon.VITE_THEMEselects it at build time; without it the default look stays. Recommended: smallest change to the currentindex.csstokens. - 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)