AIDLC-documentatie voor andreaslop-site-hosting (U1 tot en met Code Generation)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,90 @@
|
||||
# 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), feature `cms-api-foundation`
|
||||
- **To**: the CMS session `AndreaSlopFotografie` [dbb9e4], repo `SlpModularCms`
|
||||
- **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 at `aidlc-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 host `SlpModularCms.Api.AndreaSlopFotografie` with 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)
|
||||
|
||||
1. 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. `Offerings` is not referenced by Andrea's client; adding the reference later switches it on.
|
||||
2. 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.
|
||||
3. The host serves `/admin`, `/api/v1` and the website (`/`) from one process; the production host has room for only one website.
|
||||
4. Test environment only in this feature. Production, the `Master` module for Andrea, extra roles, SSR and CMS-driven site content are out of scope.
|
||||
5. Authentication is the existing Identity module unchanged (first admin via setup flow, then invitations).
|
||||
6. The admin's default language for Andrea is Dutch; English stays selectable.
|
||||
7. 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.DiscoverModules` loads `SlpModularCms.Modules.*.dll` next to the host; the client `.csproj` references decide the module set.
|
||||
- `CmsHostOptions` is empty and documented as the extension point for per-client differences; it is passed to both `CmsHost.ConfigureServices` and `ConfigurePipeline`.
|
||||
- `StaticContentExtensions` mounts `wwwroot/web` at `/` with `UseDefaultFiles` and an extensionless fallback to `index.html`. It does not map `/over-mij` to `over-mij.html` and does not serve a 404 page with status 404. The current fallback also answers unknown paths under `/api/v1` with the website `index.html`; the new mode must not.
|
||||
- `SecurityHeadersOptions.PathPolicies` plus the code-defined `CspPolicyCatalog` (`Strict`, `Relaxed`). `Strict` deliberately takes no extra script origins.
|
||||
- Admin build already reads `VITE_APP_TITLE`, `VITE_API_BASE_URL`; CI is `.gitea/workflows/continuous_integration.yaml` and `deploy-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, so `Api` and `Api.SlpSoftware` are unchanged) and `PrerenderedPages`.
|
||||
- **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. `/` serves `index.html`; `/x` serves `x.html` (also `x/index.html` if 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.html` with **status 404**, never `index.html`; plain 404 if `404.html` is missing.
|
||||
- **Reserved prefixes** `/admin`, `/api/v1`, `/health` are never handled by this middleware; an unknown API path stays an API 404.
|
||||
- **Cache-Control**: pages `no-cache`; hashed files under `/assets` long-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, nofollow` on website responses and `/robots.txt` answers `User-agent: *` / `Disallow: /`.
|
||||
- **C4 `StrictSite` policy** in `CspPolicyCatalog`: the `Strict` directives plus configured script origins in `script-src` and configured connect origins in `connect-src`; `X-Frame-Options: DENY`; `frame-ancestors 'none'`. `Strict` and `Relaxed` do not change. The new name is accepted by `PathPolicyRule` validation; unknown names still fail startup. Confirm HSTS, `X-Content-Type-Options` and `Referrer-Policy` are 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.md` and 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):
|
||||
|
||||
```text
|
||||
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): thin `Program.cs` on `CmsHost`, `WebsiteMode = PrerenderedPages`, three-file appsettings, own database, own dev port, `SecurityHeaders:DefaultPolicy = StrictSite` with the Umami and Sentry origins above, `Website:NoIndex = true` for 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_THEME` selects it at build time (unset = today's look); new `VITE_DEFAULT_LANGUAGE` (`nl` for Andrea).
|
||||
Andrea's site identity (palette from `web/src/theme.ts`, source `design/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.png` and favicon `web/public/favicon.png` in 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_LANGUAGE` and `VITE_APP_TITLE`; publish the new host; deploy to the **test** host with the existing atomic release switch; keep `wwwroot/web/` outside the swapped release directory so the website survives every CMS deploy. Do not touch the production path for `Api.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:
|
||||
1. What was built (components, files) and anything that deviates from this brief, with the reason.
|
||||
2. Test results: unit, property-based (with the seed handling you used), and the `Api`/`Api.SlpSoftware` regression run.
|
||||
3. Configuration values the website repo must know (header values, origins, hostnames, delivery path, ports).
|
||||
4. Open questions or risks.
|
||||
|
||||
I verify the hand-back by integrating it in the website repo (unit U3) and by the deployment checks there.
|
||||
Reference in New Issue
Block a user