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,97 @@
|
||||
# Requirements: cms-api-foundation ("step 0")
|
||||
|
||||
## Intent analysis
|
||||
|
||||
- **User request**: Start the API and CMS for the Andrea Slop Fotografie website on top of the owner's existing modular CMS (`SlpModularCms`, separate repo), feature by feature. This feature is **step 0**: a working CMS plus API host for the site, with per-site theming and a per-site module set (chosen by the DLLs the client references), serving both the admin and the prerendered website from one host. Packages, contact form, testimonials and shoot pages are later features.
|
||||
- **Request type**: New feature (cross-repo): extension of an existing system.
|
||||
- **Scope estimate**: Cross-system. CMS repo (new client host, shared host composition, admin frontend theming, CI) and this web repo (deploy pipeline, site build output).
|
||||
- **Complexity estimate**: Complex. Hosting model change, security headers, shared-host change that must not regress the existing SlpSoftware client.
|
||||
- **Requirements depth**: Comprehensive. Security-relevant (CSP, auth host), two repos, two AIDLC workspaces.
|
||||
- **Clarity**: Clear after the 13 clarification questions (answers in `requirement-verification-questions.md`).
|
||||
|
||||
## Context (verified by reading the CMS repo, read-only)
|
||||
|
||||
- SlpModularCms is a .NET 10 modular monolith on MariaDB. Modules: `Identity` (login, refresh, revoke, invitations, setup, users), `Master`, `Availability`, `Offerings`. Admin: Vite + React 19 + TypeScript + Tailwind v4 (primary `#ac0000`) + shadcn-style components, NL/EN.
|
||||
- Multi-site pattern today: one deployable client project per site (`Api.SlpSoftware`), a thin `Program.cs` over the shared `CmsHost` composition in `SlpModularCms.Core`, with its own database.
|
||||
- Single-host serving: one process serves `/` (site from `wwwroot/web/`), `/admin`, `/api/v1`. Reserved paths: `/admin`, `/api/v1`, `/health`. Extensionless paths currently fall back to `wwwroot/web/index.html`. The site gets the `Relaxed` CSP, the reserved paths `Strict`.
|
||||
- No theming exists; only CSS variables in the admin `index.css`.
|
||||
- This web repo: a prerendered React SPA (one HTML file per page), currently deployed as static files behind nginx (test) and IIS (production), with a strict CSP from `web/config/securityHeaders.ts`.
|
||||
|
||||
## Decisions taken in clarification
|
||||
|
||||
| # | Decision |
|
||||
|---|---|
|
||||
| Q1 | Scope covers the CMS side and the web side, proven on **test**. |
|
||||
| Q2 | The host gets a prerendered-site mode now. SSR (the owner wants it eventually, to be independent of the build pipeline) versus a hybrid (CMS blocks loaded at runtime) is decided before the first content feature. The owner checks whether the hosting partner allows a Node process. |
|
||||
| Q3 | The client project determines the CSP for `/`; Andrea's client uses the same strict CSP as the site has today. |
|
||||
| Q4 | Admin is built per site; a per-site theme file is selected at build time. No theme in the API. |
|
||||
| Q5 | The theme covers colours (existing tokens), radius, font, logo/app name and favicon. |
|
||||
| Q6 | `Offerings` is **off** for Andrea in step 0; it is switched on in the packages feature. |
|
||||
| Q7 | Users as today: first admin through the setup flow, then invitations; no new roles. |
|
||||
| Q8 | Admin default language per site; Dutch for Andrea, English remains selectable. |
|
||||
| Q9 | Only the test environment in step 0. |
|
||||
| Q10 | Hybrid collaboration with the CMS session (see Process requirements). |
|
||||
| Q11 | Security Baseline extension enforced. |
|
||||
| Q12 | Property-based testing: partial (PBT-02, 03, 07, 08, 09). |
|
||||
| Q13 | Operations phase included. |
|
||||
|
||||
## Functional requirements
|
||||
|
||||
### Client host (CMS repo)
|
||||
|
||||
- **FR-1** A new client project `SlpModularCms.Api.AndreaSlopFotografie` exists in the CMS repo, following the `Api.SlpSoftware` pattern: a thin `Program.cs` on the shared `CmsHost`, its own database, its own local dev port, the three-file appsettings pattern, and solution placement per the CMS repo's `AGENTS.md`.
|
||||
- **FR-2** The active module set of a site is the set of module projects its client host references (the existing mechanism: a module DLL that ships with the host is a module that is on). Andrea's client references only the modules the admin needs and not `Offerings`; a module that is not referenced registers nothing (no controllers or routes, no database context or migrations, no admin navigation entry) and `/api/v1/System/capabilities` lists only the referenced modules. Switching a module on later means adding its reference to the client project. No configuration filter is added to the shared host (owner decision, design stage, 2026-11-06, which supersedes the earlier "configuration switch per module" assumption).
|
||||
- **FR-3** Existing hosts (`Api`, `Api.SlpSoftware`) keep their current behaviour: same modules, same endpoints, same look, same tests passing.
|
||||
|
||||
### Theming (CMS repo, admin frontend)
|
||||
|
||||
- **FR-4** A theme is a per-site theme file (CSS tokens: colours, radius, font) plus logo, app name and favicon, stored in the CMS repo and selected when the admin is built. Without a selection, the admin keeps today's look.
|
||||
- **FR-5** The CI builds the admin once per deployable client with that client's theme. The API exposes no theme.
|
||||
- **FR-6** Andrea's theme matches the site's visual identity (source: this repo's design reference `design/andreaslop-static/` and the web theme).
|
||||
- **FR-7** The default admin language is configurable per site; Andrea's default is Dutch.
|
||||
|
||||
### Serving the site (CMS repo, shared host)
|
||||
|
||||
- **FR-8** The host has a prerendered-site mode: for a request path without a file extension it serves `{path}.html`, else `{path}/index.html`; for an unknown path it serves the site's 404 page with HTTP status 404. URLs have no trailing slash, query strings are preserved, and the reserved paths `/admin`, `/api/v1` and `/health` always win.
|
||||
- **FR-9** Existing behaviour (SPA fallback) remains available for sites that do not use the prerendered mode, so SlpSoftware is unaffected.
|
||||
- **FR-10** The CSP (and the other security headers) for `/` is set per client project. Andrea's client reproduces the strict policy of `web/config/securityHeaders.ts`. A mechanism keeps the two from drifting apart (decided in design).
|
||||
|
||||
### Authentication
|
||||
|
||||
- **FR-11** Authentication is the existing Identity module, unchanged: first administrator via the setup flow, then invitations, no new roles. For Andrea's instance the setup flow must not be reachable by anyone else once the first administrator exists.
|
||||
|
||||
### Web repo (this repo)
|
||||
|
||||
- **FR-12** The site build output (prerendered pages, assets, 404 page) can be delivered to `wwwroot/web/` of Andrea's CMS host on test as part of the deploy, without a manual step.
|
||||
- **FR-13** The web CI is adapted for that delivery. Removing the static nginx deployment of the test site is part of the switch, but only after the new route works.
|
||||
- **FR-14** Proof on test: the home page and at least one sub page are served prerendered, an unknown path returns the 404 page with status 404, `/admin` shows Andrea's theme and allows login, `/health` and `/api/v1/System/capabilities` respond and show `Offerings` off.
|
||||
|
||||
### Process
|
||||
|
||||
- **FR-15** The CMS work is handed to the CMS session (`AndreaSlopFotografie`, `dbb9e4`) as a feature brief per feature; the CMS session runs its own AIDLC. This session answers web-side questions; CMS-internal, security and data-model decisions go to the owner, who approves the CMS requirements and design. The result is handed back as an artifact (changed contract and changelog) which this session verifies by integrating it.
|
||||
|
||||
## Non-functional requirements
|
||||
|
||||
- **NFR-1 Security (Security Baseline enforced).** Applicable rules for step 0: SECURITY-03 (structured logging, no secrets in logs), SECURITY-04 (security headers on all HTML endpoints; no `unsafe-inline` or `unsafe-eval` without documented justification), SECURITY-05 (input validation, existing endpoints), SECURITY-08 (deny by default, CORS only for allowed origins, server-side token validation), SECURITY-09 (no default credentials, generic production errors, no directory listing, no sample content), SECURITY-10 (lock files, vulnerability scan step, pinned CI versions), SECURITY-11 (rate limiting on login, misuse case for the setup flow), SECURITY-12 (credential and session handling as existing; no committed secrets), SECURITY-13 (build integrity), SECURITY-15 (global error handler, fail closed). SECURITY-01, 02, 06, 07 and 14 are assessed per stage (database TLS and encryption at rest, access logging on the reverse proxy, least privilege of the deploy identity, network exposure of the Pi, alerting). Non-compliance is a blocking finding.
|
||||
- **NFR-2 No security regression.** Moving the site behind the CMS host must not weaken the headers the site has today (see FR-10).
|
||||
- **NFR-3 Performance.** Prerendered pages are served as static files with compression and long-lived caching for hashed assets, and the site's Lighthouse targets (see the open follow-ups) must not drop compared to the nginx deployment.
|
||||
- **NFR-4 Compatibility.** Existing hosts and tests keep working (FR-3); the shared `CmsHost` change is backward compatible by default.
|
||||
- **NFR-5 Deployability.** Runs on the test Pi (ARM64, MariaDB) through the existing Gitea CI/CD with its atomic release switch. `wwwroot/web/` stays outside the swapped release directory so a CMS deploy does not remove the site.
|
||||
- **NFR-6 Testing.** Unit and integration tests for module composition (a client without a module exposes none of its routes), prerendered-site serving (including 404 status and reserved paths) and header configuration. Property-based tests (partial mode, PBT-02, 03, 07, 08, 09) for pure functions and round-trips, for example path-to-file resolution and configuration parsing.
|
||||
- **NFR-7 Maintainability.** Per-site differences live in the client project and the theme file; the shared host contains no site names.
|
||||
- **NFR-8 Documentation.** CMS repo docs (`WEBSITE_WORKSPACE.md`, README) are updated for the prerendered mode, module composition per client and themes.
|
||||
|
||||
## Out of scope for step 0
|
||||
|
||||
Offerings/packages, contact form, testimonials, shoot pages and media upload; SSR or the hybrid runtime content loading (decided before the first content feature); production cutover and the IIS hosting; the `Master` module for Andrea; roles; a theme editor in the admin; changes to files owned by the Testimonials session.
|
||||
|
||||
## Open items and risks
|
||||
|
||||
- **Hosting partner**: whether a Node process (SSR) is possible on `mijnhostingpartner.nl`, and whether the production host runs .NET, is unknown. The owner checks this; it does not block step 0.
|
||||
- **CSP source of truth**: the site's policy lives in `web/config/securityHeaders.ts`. How the CMS client project gets the same values without drifting (generated artifact, shared file, or test that compares) is a design decision.
|
||||
- **Parallel work**: the Testimonials session edits `aidlc-docs/active-features.md` (row-level merge conflict expected) and web components. This feature touches `web/` only for the deploy pipeline, and only after the Testimonials feature has merged or confirmed no overlap.
|
||||
- **Dev ports and databases**: Andrea's client needs its own dev port and local database, as `Api.SlpSoftware` has.
|
||||
|
||||
## Direction note (owner, 2026-11-06, tracked by the website session)
|
||||
|
||||
More and more of the website will become dynamic (CMS-driven), so the share of purely prerendered, static serving is expected to shrink over time. This is not a change to step 0: the prerendered-site mode stays as designed. It is an input to the decision on SSR versus a hybrid (CMS blocks loaded at runtime), which must be taken before the first content feature (packages), together with the answer to whether the hosting partner allows a Node process. Design consequence to keep in mind: the host's prerendered mode and its nginx-parity rules must stay usable next to dynamic content (for example as the fallback for pages that are not CMS-driven).
|
||||
Reference in New Issue
Block a user