Adds the AI-DLC documents of the CMS and API foundation feature
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,90 @@
|
||||
# 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
|
||||
|
||||
- [x] Analyze requirements and read the CMS host code (read-only)
|
||||
- [x] Collect answers to the design questions below
|
||||
- [x] Analyze answers for ambiguity; ask follow-ups if needed (none: Q1 clarified in chat and applied to FR-2)
|
||||
- [x] Generate `application-design/components.md`
|
||||
- [x] Generate `application-design/component-methods.md`
|
||||
- [x] Generate `application-design/services.md`
|
||||
- [x] Generate `application-design/component-dependency.md`
|
||||
- [x] Generate `application-design/application-design.md` (consolidated)
|
||||
- [x] 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)
|
||||
|
||||
[Answer]: B (owner: a module is on when its DLL is added to the client; no config filter, and not all functionality is built into every client)
|
||||
|
||||
### 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)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
### 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)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
### 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)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
### 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)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
### 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)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
### 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)
|
||||
|
||||
[Answer]: B (owner chose a copy in the CMS repo)
|
||||
Reference in New Issue
Block a user