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:
+43
@@ -0,0 +1,43 @@
|
||||
# Application Design: cms-api-foundation (consolidated)
|
||||
|
||||
Details: [components.md](components.md), [component-methods.md](component-methods.md), [services.md](services.md), [component-dependency.md](component-dependency.md).
|
||||
|
||||
## Summary
|
||||
|
||||
Andrea's site runs from a new client host, `SlpModularCms.Api.AndreaSlopFotografie`, in the CMS repo. The host serves the admin (`/admin`), the API (`/api/v1`) and the prerendered site (`/`) in one process. Additive changes to the shared host give it a prerendered-site mode with the hosting behaviour nginx provides today, and a third code-defined CSP policy, `StrictSite`. The admin gets a per-site theme and default language through build-time variables. The web repo gains a delivery job and an extended deployment check that doubles as the CSP drift guard.
|
||||
|
||||
## Design decisions
|
||||
|
||||
| # | Decision | Consequence |
|
||||
|---|---|---|
|
||||
| D1 | A site's modules = the module projects its client references (existing DLL mechanism). No config filter. | No new filter code. Andrea does not reference `Offerings`; adding the reference later switches it on. Requirements FR-2 updated accordingly. |
|
||||
| D2 | New policy `StrictSite` in `CspPolicyCatalog`. | Admin `Strict` unchanged. Site CSP equals the current nginx one when the origin lists match. |
|
||||
| D3 | CSP drift guard = exact-CSP assertion in the web repo's `verify-deployment.sh`. | Cross-repo coupling stays in one script; drift fails the web deploy. |
|
||||
| D4 | Hosting parity for what the site relies on: canonical redirects, `404.html` with status 404, cache rules, text compression, per-environment `noindex` and `robots.txt`. | The host replaces nginx without changing SEO behaviour; test is not indexed. |
|
||||
| D5 | Serving mode is code (`CmsHostOptions` in the client's `Program.cs`); environment-dependent settings are appsettings. | `SpaFallback` stays the default, so `Api` and `Api.SlpSoftware` do not change. |
|
||||
| D6 | Theme = folder with CSS token overrides and assets, selected with `VITE_THEME`; default language with `VITE_DEFAULT_LANGUAGE`. | One admin source tree, one build per client; no theme API. |
|
||||
| D7 | The brief lives in this repo and a copy is placed in the CMS repo's AIDLC folder. | The location inside the CMS workspace is agreed with the CMS session when handing over. |
|
||||
| D8 | Reserved prefixes (`/admin`, `/api/v1`, `/health`) are never handled by the website middleware. | An unknown API path remains an API 404 instead of the site's 404 page. |
|
||||
|
||||
## Security Baseline compliance (design level)
|
||||
|
||||
| Rule | Status | Note |
|
||||
|---|---|---|
|
||||
| SECURITY-04 headers | Compliant by design | `StrictSite` carries a restrictive CSP (no `unsafe-inline` in `script-src`, no `unsafe-eval`); HSTS, nosniff, DENY and Referrer-Policy come from the existing header writer. To confirm in Functional Design: HSTS is emitted for the website path. `style-src 'unsafe-inline'` is the existing, documented exception (Chakra/Emotion runtime styles). |
|
||||
| SECURITY-05 input validation | Compliant by design | The only new input is the request path: the resolver is total, rejects traversal and never leaves the website root. Property tests (PBT-03 invariants) planned. |
|
||||
| SECURITY-08 access control | Compliant | The site is public by intent; `/admin` and `/api/v1` unchanged. |
|
||||
| SECURITY-09 hardening | To verify | No directory listing (resolver serves files only); generic errors by the existing handler. The first-administrator setup endpoint on the new instance must be protected until the first admin exists (NFR/FR-11), assessed in NFR Requirements. |
|
||||
| SECURITY-10 supply chain | Compliant | No new dependencies (built-in response compression); lock files stay committed. |
|
||||
| SECURITY-11 secure design | Compliant | Security logic stays in dedicated catalog and header components. Misuse case: path traversal and cache poisoning through non-canonical URLs, handled by the resolver. Rate limiting stays on login. |
|
||||
| SECURITY-13 integrity | Compliant | Delivery is by the pipelines; CSP drift guard added. |
|
||||
| SECURITY-15 fail safe | Compliant | Unknown policy names fail startup; missing `404.html` falls back to a plain 404. |
|
||||
| SECURITY-01, 02, 03, 06, 07, 14 | Deferred | Assessed in NFR Requirements and Infrastructure Design (database TLS, proxy access logs, deploy identity, network exposure, alerting). |
|
||||
|
||||
No blocking security findings at this stage.
|
||||
|
||||
## Open items for the next stages
|
||||
|
||||
- Which module projects the new host must reference at minimum (Identity and Availability dependency) is a Functional Design finding of the CMS session.
|
||||
- Exact canonicalisation rules and the file-resolution order are Functional Design, derived from `web/config/canonicalUrls.ts` and the web's BR-HST rules.
|
||||
- Whether the test host's existing reverse proxy (nginx on the Pi) stays in front of the CMS host (TLS, access logs) is decided in Infrastructure Design.
|
||||
- Node/SSR remains undecided and is outside step 0 (requirements Q2).
|
||||
+85
@@ -0,0 +1,85 @@
|
||||
# Component Dependencies: cms-api-foundation
|
||||
|
||||
## Dependency matrix
|
||||
|
||||
Rows depend on columns ("x" = depends on).
|
||||
|
||||
| | C1 host | C2 options | C3 site serving | C4 StrictSite | C5 theme | C6 CMS CI | C7 delivery | C8 verify |
|
||||
|---|---|---|---|---|---|---|---|---|
|
||||
| **C1 Api.AndreaSlopFotografie** | | x | x (via CmsHost) | x (config) | | | | |
|
||||
| **C2 CmsHostOptions** | | | | | | | | |
|
||||
| **C3 Site serving** | | x | | | | | | |
|
||||
| **C4 StrictSite** | | | | | | | | |
|
||||
| **C5 Theme** | | | | | | | | |
|
||||
| **C6 CMS CI** | x | | | | x | | | |
|
||||
| **C7 Site delivery** | x (target) | | | | | x (host exists) | | |
|
||||
| **C8 Verify** | x (live) | | x (behaviour) | x (behaviour) | | | x | |
|
||||
|
||||
## Dependency diagram
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
C2["C2 CmsHostOptions"]
|
||||
C3["C3 Prerendered site serving"]
|
||||
C4["C4 StrictSite policy"]
|
||||
C1["C1 Api.AndreaSlopFotografie"]
|
||||
C5["C5 Admin theme"]
|
||||
C6["C6 CMS CI"]
|
||||
C7["C7 Site delivery (web repo)"]
|
||||
C8["C8 Deployment verification (web repo)"]
|
||||
C3 --> C2
|
||||
C1 --> C2
|
||||
C1 --> C3
|
||||
C1 --> C4
|
||||
C6 --> C1
|
||||
C6 --> C5
|
||||
C7 --> C6
|
||||
C8 --> C7
|
||||
C8 -. checks .-> C3
|
||||
C8 -. checks .-> C4
|
||||
classDef cms fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef web fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef newc fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
class C2,C3,C4,C5,C6 cms;
|
||||
class C7,C8 web;
|
||||
class C1 newc;
|
||||
```
|
||||
|
||||
Text alternative: The new client host depends on the options, site serving and the StrictSite policy; the CMS CI builds the host and theme; the web repo's delivery depends on the CMS CI having deployed the host; verification checks the live behaviour of serving and policy. Blue = CMS repo, green = web repo, yellow = new client host.
|
||||
|
||||
## Communication patterns
|
||||
|
||||
- **Compile time**: the client project references `Core` and its modules (this is also what selects the modules). `CmsHostOptions` is passed in code.
|
||||
- **Configuration**: `SecurityHeaders` and `Website` sections per environment (appsettings; no secrets).
|
||||
- **Build time**: the admin reads `VITE_*` variables; nothing about the theme reaches the API.
|
||||
- **Deploy time**: the CMS CI delivers the release; the web CI delivers site files into `wwwroot/web/`. The two never write into each other's directories.
|
||||
- **Runtime**: the browser calls the host same-origin for everything (site, `/admin`, `/api/v1`); no CORS for the site.
|
||||
|
||||
## Data flow: a request for a site page
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
R["Browser request /over-mij"]
|
||||
H["Security headers (StrictSite)"]
|
||||
RES["PrerenderedPathResolver"]
|
||||
F["Serve over-mij.html"]
|
||||
RD["301 to canonical path"]
|
||||
NF["404.html, status 404"]
|
||||
R --> H --> RES
|
||||
RES -->|file found| F
|
||||
RES -->|non-canonical form| RD
|
||||
RES -->|unknown| NF
|
||||
classDef step fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef ok fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef bad fill:#fc8181,stroke:#c53030,stroke-width:1px,color:#000;
|
||||
class R,H,RES step;
|
||||
class F,RD ok;
|
||||
class NF bad;
|
||||
```
|
||||
|
||||
Text alternative: A page request gets the security headers, then the path resolver decides between serving the page file, redirecting to the canonical URL or returning the 404 page with status 404.
|
||||
|
||||
## Cross-session dependencies
|
||||
|
||||
- C7 and C8 changes in `web/deploy` and CI are the only web-repo changes; they start after the Testimonials feature has merged or overlap is ruled out.
|
||||
- C1 to C6 are built by the CMS session; their approved design and hand-back are recorded in `construction/cms-host/`.
|
||||
+86
@@ -0,0 +1,86 @@
|
||||
# Component Methods: cms-api-foundation
|
||||
|
||||
High-level signatures only. Business rules (exact canonicalisation, edge cases, error handling) are defined in Functional Design by the CMS session. Names are indicative; the CMS session may rename them.
|
||||
|
||||
## C2. `CmsHostOptions`
|
||||
|
||||
```csharp
|
||||
public enum WebsiteMode { SpaFallback = 0, PrerenderedPages = 1 }
|
||||
|
||||
public sealed class CmsHostOptions
|
||||
{
|
||||
public WebsiteMode WebsiteMode { get; init; } = WebsiteMode.SpaFallback;
|
||||
}
|
||||
```
|
||||
|
||||
## C3a. `PrerenderedPathResolver` (pure)
|
||||
|
||||
```csharp
|
||||
public abstract record SiteResolution;
|
||||
public sealed record ServeFile(string RelativePath, bool IsPage) : SiteResolution; // IsPage drives cache policy
|
||||
public sealed record RedirectTo(string CanonicalPath) : SiteResolution; // 301, query added by caller
|
||||
public sealed record NotFound() : SiteResolution;
|
||||
|
||||
public sealed class PrerenderedPathResolver
|
||||
{
|
||||
public PrerenderedPathResolver(Func<string, bool> fileExists);
|
||||
public SiteResolution Resolve(PathString requestPath); // total: never throws, never escapes the root
|
||||
}
|
||||
```
|
||||
|
||||
## C3b. Middleware wiring
|
||||
|
||||
```csharp
|
||||
public static IApplicationBuilder UseCmsPrerenderedSite(this WebApplication app, CmsHostOptions options);
|
||||
// - registered where UseCmsStaticContent registers the website mount
|
||||
// - skips reserved prefixes: /admin, /api/v1, /health
|
||||
// - NotFound -> serve 404.html with status 404 (plain 404 if 404.html is missing)
|
||||
```
|
||||
|
||||
## C3c. `WebsiteCachePolicy`
|
||||
|
||||
```csharp
|
||||
public static string CacheControlFor(SiteResolution resolution); // pages: "no-cache"; /assets/*: long-lived immutable; other files: short default
|
||||
```
|
||||
|
||||
## C3d. `WebsiteIndexingPolicy`
|
||||
|
||||
```csharp
|
||||
public sealed class WebsiteOptions { public bool NoIndex { get; set; } } // section "Website"
|
||||
public static IEndpointRouteBuilder MapCmsRobots(this IEndpointRouteBuilder app, WebsiteOptions options);
|
||||
// NoIndex: adds X-Robots-Tag header to website responses and answers /robots.txt "User-agent: *\nDisallow: /"
|
||||
```
|
||||
|
||||
## C4. `CspPolicyCatalog`
|
||||
|
||||
```csharp
|
||||
public const string StrictSite = "StrictSite";
|
||||
public static SecurityHeaderSet Build(string policy, IEnumerable<string> scriptOrigins, IEnumerable<string> connectOrigins);
|
||||
// StrictSite: script-src 'self' + scriptOrigins; connect-src 'self' + connectOrigins; FrameOptions "DENY".
|
||||
// Strict and Relaxed unchanged. KnownPolicies includes StrictSite.
|
||||
```
|
||||
|
||||
## C1. `Api.AndreaSlopFotografie/Program.cs`
|
||||
|
||||
```csharp
|
||||
var orchestrator = CmsHost.ConfigureServices(builder, new CmsHostOptions { WebsiteMode = WebsiteMode.PrerenderedPages });
|
||||
var app = builder.Build();
|
||||
CmsHost.ConfigurePipeline(app, orchestrator, new CmsHostOptions { WebsiteMode = WebsiteMode.PrerenderedPages });
|
||||
```
|
||||
|
||||
## C5. Admin theme selection (build time)
|
||||
|
||||
```text
|
||||
VITE_THEME -> frontend/themes/<name>/theme.css (+ logo, favicon); unset = default theme
|
||||
VITE_DEFAULT_LANGUAGE -> "nl" | "en"; unset = current default
|
||||
VITE_APP_TITLE -> existing
|
||||
```
|
||||
|
||||
## C8. Deployment verification (shell, extends the existing script)
|
||||
|
||||
```text
|
||||
verify_csp_equals <url> <expectedCsp> # expectedCsp generated from contentSecurityPolicy('production')
|
||||
verify_status <url> <expectedStatus>
|
||||
verify_redirect <url> <expectedLocation>
|
||||
verify_header <url> <name> <expectedValue|absent>
|
||||
```
|
||||
@@ -0,0 +1,64 @@
|
||||
# Components: cms-api-foundation
|
||||
|
||||
Repository: **CMS** = `K:\Development\Projects\SlpModularCms`, **WEB** = this repo. Components marked "new" do not exist yet; "changed" exist and get an additive change. Everything under CMS is built by the CMS session in its own AIDLC; it may rename types, the responsibilities and interfaces are the contract.
|
||||
|
||||
## CMS repo
|
||||
|
||||
### C1. `SlpModularCms.Api.AndreaSlopFotografie` (new, client host)
|
||||
- **Purpose**: The deployable host for Andrea's site: admin, API and the prerendered website in one process.
|
||||
- **Responsibilities**:
|
||||
- Thin `Program.cs` on the shared `CmsHost`, like `Api.SlpSoftware`.
|
||||
- Module composition: references `Core` and only the module projects Andrea needs. `Offerings` is not referenced. Which other modules are required (Identity, and possibly Availability) is a Functional Design finding of the CMS session.
|
||||
- Sets `CmsHostOptions.WebsiteMode = PrerenderedPages`.
|
||||
- Own appsettings (three-file pattern), own database, own dev port.
|
||||
- Security header configuration: `SecurityHeaders:DefaultPolicy = StrictSite` and `AllowedScriptOrigins` / `AllowedConnectOrigins` for Umami and Sentry.
|
||||
- Website indexing setting (`Website:NoIndex`) per environment.
|
||||
- **Interfaces**: the shared `CmsHost.ConfigureServices` / `ConfigurePipeline` calls; configuration sections `SecurityHeaders`, `Website`.
|
||||
|
||||
### C2. `CmsHostOptions` (changed, in Core)
|
||||
- **Purpose**: The documented extension point for per-client differences.
|
||||
- **Responsibilities**: carries `WebsiteMode` (`SpaFallback` default, `PrerenderedPages`). The default keeps `Api` and `Api.SlpSoftware` unchanged.
|
||||
- **Interface**: `WebsiteMode WebsiteMode { get; init; }`.
|
||||
|
||||
### C3. Prerendered website serving (new, in Core `Hosting`)
|
||||
Four parts, replacing the website half of `UseCmsStaticContent` and `MapCmsSpaFallbacks` when `WebsiteMode = PrerenderedPages`:
|
||||
- **C3a `PrerenderedPathResolver`** (pure function, no I/O beyond a file-existence predicate): maps a request path to one of `Serve(file)`, `Redirect(canonicalPath)`, `NotFound`. Rules: `/` serves `index.html`; `/x` serves `x.html` (also `x/index.html` if present); canonical form is lowercase, without `.html`, without trailing slash, query preserved; paths that look like a file are served as files or 404; traversal attempts never leave the website root; reserved prefixes (`/admin`, `/api/v1`, `/health`) are never handled here.
|
||||
- **C3b `PrerenderedSiteMiddleware`**: applies the resolver, serves files, answers `404.html` with status 404 for unknown paths (never `index.html`), issues canonical 301 redirects, and excludes reserved prefixes so an unknown `/api/v1/x` stays a plain API 404, not the website's 404 page.
|
||||
- **C3c `WebsiteCachePolicy`**: `Cache-Control: no-cache` for pages, long-lived immutable for hashed `/assets`.
|
||||
- **C3d `WebsiteIndexingPolicy`**: when `Website:NoIndex` is true, adds `X-Robots-Tag: noindex, nofollow` and serves `/robots.txt` as "disallow all". Off by default.
|
||||
- **Compression** uses the built-in ASP.NET response compression for the same text types as `web/config/compressibleTypes.ts`; no new dependency.
|
||||
|
||||
### C4. `CspPolicyCatalog.StrictSite` (changed, in Core `Hosting/Security`)
|
||||
- **Purpose**: The third code-defined policy for a strict, script-from-self public site.
|
||||
- **Responsibilities**: `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. `PathPolicyRule` and startup validation accept the new name (unknown names still fail startup).
|
||||
- **Interface**: `CspPolicyCatalog.Build("StrictSite", scriptOrigins, connectOrigins) -> SecurityHeaderSet`.
|
||||
|
||||
### C5. Admin theming (changed, CMS `frontend/`)
|
||||
- **Purpose**: Make the admin match a site's identity without per-site code.
|
||||
- **Responsibilities**:
|
||||
- Default theme = today's tokens in `index.css`.
|
||||
- A theme folder `frontend/themes/<name>/` with a CSS file overriding the tokens (colours, radius, font) and the assets (logo, favicon).
|
||||
- `VITE_THEME` selects the folder at build time; `VITE_APP_TITLE` already names the app; a new build-time `VITE_DEFAULT_LANGUAGE` sets the default admin language (NL for Andrea, EN remains selectable).
|
||||
- First theme: `themes/andreaslop/` from the site's identity (source: `design/andreaslop-static/` and the web theme in this repo).
|
||||
- **Interface**: build-time environment variables only. No API.
|
||||
|
||||
### C6. CMS CI/CD (changed, `.gitea/workflows/continuous_integration.yaml`, `deploy-scp.yaml`)
|
||||
- **Purpose**: Build and deploy Andrea's host.
|
||||
- **Responsibilities**: build the admin once per deployable client with its `VITE_THEME` / `VITE_DEFAULT_LANGUAGE` / `VITE_APP_TITLE`; publish `Api.AndreaSlopFotografie`; deploy to the test host with the existing atomic release switch; keep `wwwroot/web/` outside the swapped release directory.
|
||||
|
||||
## WEB repo (this repo)
|
||||
|
||||
### C7. Site delivery (new)
|
||||
- **Purpose**: Get the prerendered build onto Andrea's CMS host.
|
||||
- **Responsibilities**: a CI job that builds the site and delivers the output (`index.html`, `*.html`, `404.html`, `assets/`, `robots`/sitemap files as built) to `wwwroot/web/` of the test host; keeps the old nginx deployment until the new route passes; afterwards retires the static test site.
|
||||
- **Interface**: file delivery into `wwwroot/web/` (the contract in the CMS repo's `WEBSITE_WORKSPACE.md`).
|
||||
|
||||
### C8. Deployment verification (changed, `web/deploy/verify-deployment.sh`)
|
||||
- **Purpose**: Prove the new host serves the site as the old one did, and guard CSP drift.
|
||||
- **Responsibilities**: assert the exact CSP from `contentSecurityPolicy('production')` (`web/config/securityHeaders.ts`) and the other security headers; assert canonical redirects, `404.html` with status 404, caching and `noindex` on test; assert that `/admin`, `/api/v1/System/capabilities` and `/health` respond.
|
||||
|
||||
## Process component
|
||||
|
||||
### C9. Hand-off (new, documents)
|
||||
- **Purpose**: Moves a feature brief to the CMS session and brings the result back.
|
||||
- **Responsibilities**: the brief is written in this repo's AIDLC folder and a copy is placed in the CMS repo's AIDLC folder (owner decision). The CMS session runs its own AIDLC. The hand-back is a changelog plus the changed contract, verified here by the C8 checks.
|
||||
@@ -0,0 +1,54 @@
|
||||
# Services: cms-api-foundation
|
||||
|
||||
The solution has no new domain services: step 0 adds hosting behaviour (middleware and policy) and build/deploy automation. This document defines the orchestration points.
|
||||
|
||||
## S1. Host composition (`CmsHost`)
|
||||
|
||||
- **Responsibility**: single place where a client host's services and pipeline are composed. `ConfigureServices` and `ConfigurePipeline` keep their signatures; the new behaviour enters through `CmsHostOptions`.
|
||||
- **Orchestration (pipeline order, with the reason)**:
|
||||
1. `MigrateCoreDatabase` (unchanged).
|
||||
2. Exception handler, then security headers, then rate limiter (unchanged). Security headers must stay before static content: static files short-circuit the pipeline, and the website's HTML is almost all the host serves.
|
||||
3. HTTPS redirection (unchanged).
|
||||
4. **Static content**: admin mount first (unchanged). The website mount is either the existing static mount plus SPA fallback (`SpaFallback`) or the prerendered-site middleware (`PrerenderedPages`). Response compression sits before both.
|
||||
5. CORS, modules, authentication, authorization, controllers, health, Sentry tunnel (unchanged).
|
||||
6. The website fallback (`NotFound` -> `404.html`) is the last step, after the API routes, so an unknown API path stays an API 404.
|
||||
- **Invariant**: reserved prefixes `/admin`, `/api/v1`, `/health` are never resolved by the website middleware.
|
||||
|
||||
## S2. Security header resolution (existing `PathPolicyResolver` + `CspPolicyCatalog`)
|
||||
|
||||
- **Responsibility**: path -> policy name (configuration) -> header values (code).
|
||||
- **Change**: the catalog knows `StrictSite`. Andrea's client sets `DefaultPolicy = StrictSite`; the three reserved prefixes stay `Strict`. Startup validation rejects unknown names (unchanged), so a typo cannot produce a weaker policy.
|
||||
|
||||
## S3. Build and deploy service chain (CI)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
box rgba(246,224,94,0.4) CMS repo
|
||||
participant CC as CMS CI
|
||||
end
|
||||
box rgba(99,179,237,0.4) Web repo
|
||||
participant WC as Web CI
|
||||
end
|
||||
box rgba(154,230,180,0.4) Test host
|
||||
participant H as Andrea CMS host
|
||||
end
|
||||
CC->>CC: build admin with VITE_THEME andreaslop
|
||||
CC->>CC: publish Api.AndreaSlopFotografie
|
||||
CC->>H: deploy release, atomic switch
|
||||
WC->>WC: build prerendered site
|
||||
WC->>H: deliver files to wwwroot/web
|
||||
WC->>H: verify headers, redirects, 404, CSP
|
||||
H-->>WC: results
|
||||
```
|
||||
|
||||
Text alternative: the CMS CI builds and deploys the host with its themed admin; the web CI builds the site, delivers it into the host's website folder and then verifies the host's behaviour.
|
||||
|
||||
- **Ordering rules**: the CMS release switch never touches `wwwroot/web/`; the web delivery is idempotent and can run without a CMS deploy; the old static test site stays up until verification passes.
|
||||
|
||||
## S4. Verification service (`verify-deployment.sh`)
|
||||
|
||||
- **Responsibility**: the contract test between the repositories. It runs from the web repo against the live host and is the CSP drift guard (design decision Q3).
|
||||
|
||||
## S5. Hand-off service (process)
|
||||
|
||||
- **Responsibility**: brief out, hand-back in; see C9. The CMS session's AIDLC outputs (its design summary and its hand-back note) are copied or linked under `construction/cms-host/` in this feature.
|
||||
+38
@@ -0,0 +1,38 @@
|
||||
# Unit of Work Dependencies: cms-api-foundation
|
||||
|
||||
## Dependency matrix
|
||||
|
||||
Rows depend on columns.
|
||||
|
||||
| | U1 core-site-hosting | U2 andreaslop-client | U3 site-delivery |
|
||||
|---|---|---|---|
|
||||
| **U1 core-site-hosting** | | | |
|
||||
| **U2 andreaslop-client** | x (code: `WebsiteMode`, `StrictSite`) | | |
|
||||
| **U3 site-delivery** | | x (a deployed host to deliver into and verify) | |
|
||||
|
||||
## Diagram
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
U1["U1 core-site-hosting<br/>(CMS repo)"]
|
||||
U2["U2 andreaslop-client<br/>(CMS repo)"]
|
||||
U3["U3 site-delivery<br/>(web repo)"]
|
||||
CP1{{"Checkpoint: hand-back after U1"}}
|
||||
U1 --> CP1 --> U2 --> U3
|
||||
classDef cms fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef web fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef gate fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
class U1,U2 cms;
|
||||
class U3 web;
|
||||
class CP1 gate;
|
||||
```
|
||||
|
||||
Text alternative: U1 and U2 are built in the CMS repo, with a hand-back checkpoint after U1; U3 in the web repo follows U2. Blue = CMS repo, green = web repo, yellow = checkpoint.
|
||||
|
||||
## Sequence and coordination
|
||||
|
||||
- **Critical path**: U1, U2, U3. No parallelism between units, because each needs the previous one's result; inside U2 the admin theme can be built in parallel with the host project.
|
||||
- **Checkpoint after U1**: `Api` and `Api.SlpSoftware` tests green and the hand-back note delivered. U2 starts only then (the brief for both units tells the CMS session to report here).
|
||||
- **Coordination points**: the reserved paths and the `wwwroot/web/` contract; the 404 page name (`404.html`) and the page files without folders (`name.html`); the exact CSP value (checked by U3); the host name and database of the test instance (decided in U2 Infrastructure Design).
|
||||
- **External dependency for U3**: the Testimonials feature merged, or overlap ruled out, because U3 touches the web CI and `web/deploy/`.
|
||||
- **Rollback**: U1 is additive and inactive by default (`SpaFallback`); U2 deploys a new host alongside the old test site; U3 retires the static test site only after verification, so every step can be reverted on test without data loss.
|
||||
+35
@@ -0,0 +1,35 @@
|
||||
# Unit of Work Requirement Map: cms-api-foundation
|
||||
|
||||
User Stories were skipped (one persona; see the execution plan). This map assigns each requirement to its unit(s) instead. "Primary" owns the work; "also" contributes or verifies.
|
||||
|
||||
| Requirement | Summary | Primary unit | Also |
|
||||
|---|---|---|---|
|
||||
| FR-1 | Client project `Api.AndreaSlopFotografie` | U2 | |
|
||||
| FR-2 | Module set = referenced module projects | U2 | |
|
||||
| FR-3 | Existing hosts unchanged | U1 | U2 (SlpSoftware still builds and deploys) |
|
||||
| FR-4 | Per-site theme file, selected at build | U2 | |
|
||||
| FR-5 | Admin built per client in CI | U2 | |
|
||||
| FR-6 | Andrea's theme matches the site | U2 | |
|
||||
| FR-7 | Default admin language per site | U2 | |
|
||||
| FR-8 | Prerendered-site serving mode | U1 | |
|
||||
| FR-9 | SPA fallback remains available | U1 | |
|
||||
| FR-10 | CSP for `/` per client, no drift | U1 (policy) | U2 (configuration), U3 (drift check) |
|
||||
| FR-11 | Authentication unchanged, setup flow safe | U2 | |
|
||||
| FR-12 | Site build delivered to `wwwroot/web/` | U3 | U2 (target host) |
|
||||
| FR-13 | Web CI adapted, static test site retired after proof | U3 | |
|
||||
| FR-14 | Proof on test | U3 | Build and Test (phase level) |
|
||||
| FR-15 | Collaboration with the CMS session | Process (this session) | all units |
|
||||
| NFR-1 | Security Baseline | all units | U2 (setup flow, logging), U1 (headers, path input) |
|
||||
| NFR-2 | No security regression | U1 | U3 (exact CSP check) |
|
||||
| NFR-3 | Performance (compression, caching, Lighthouse) | U1 | U3 (Lighthouse comparison) |
|
||||
| NFR-4 | Compatibility with existing hosts | U1 | |
|
||||
| NFR-5 | Deployability on the Pi, atomic switch | U2 | U3 |
|
||||
| NFR-6 | Testing incl. partial PBT | U1 | U2 |
|
||||
| NFR-7 | Per-site differences only in client and theme | U2 | U1 |
|
||||
| NFR-8 | Documentation | U1 | U2 |
|
||||
|
||||
## Validation
|
||||
|
||||
- Every FR (1 to 15) and NFR (1 to 8) is assigned to a unit or to the process.
|
||||
- Every component C1 to C8 belongs to exactly one unit: C2, C3, C4 to U1; C1, C5, C6 to U2; C7, C8 to U3. C9 (hand-off) is the process component.
|
||||
- No unit depends on a later unit.
|
||||
@@ -0,0 +1,37 @@
|
||||
# Units of Work: cms-api-foundation
|
||||
|
||||
Three units. Terminology: a unit is a planning and build unit of one deployable system (the CMS host plus its admin) split into logical chunks; nothing here becomes an independently deployable service. Repository paths: **CMS** = `K:\Development\Projects\SlpModularCms`, **WEB** = this repo.
|
||||
|
||||
## U1 `core-site-hosting` (CMS repo, built by the CMS session)
|
||||
|
||||
- **Purpose**: 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.
|
||||
- **Components**: C2 `CmsHostOptions.WebsiteMode`, C3 prerendered site serving (resolver, middleware, cache policy, indexing policy, compression), C4 `StrictSite` policy.
|
||||
- **Requirements**: FR-3, FR-8, FR-9, FR-10 (policy part), NFR-2, NFR-3, NFR-4, NFR-6 (resolver and policy tests), NFR-8 (CMS docs).
|
||||
- **Construction stages**: Functional Design, NFR Requirements, NFR Design, Infrastructure Design (only if the host change touches deployment; expected none), Code Generation.
|
||||
- **Done when**: unit and property-based tests pass; `Api` and `Api.SlpSoftware` behave unchanged (their tests green); `WEBSITE_WORKSPACE.md` and README describe the mode; the hand-back note is written. **Checkpoint**: the CMS session reports back after U1 before starting U2.
|
||||
- **Code location**: `src/SlpModularCms.Core/Hosting` (and `.../Security`) plus `src/SlpModularCms.Core.Tests`.
|
||||
|
||||
## U2 `andreaslop-client` (CMS repo, built by the CMS session)
|
||||
|
||||
- **Purpose**: Andrea's own host with a themed Dutch admin, deployed to test through the CMS CI/CD.
|
||||
- **Components**: C1 `SlpModularCms.Api.AndreaSlopFotografie` (project, appsettings, database, dev port, module references without `Offerings`, `WebsiteMode = PrerenderedPages`, `SecurityHeaders` and `Website` configuration), C5 admin theme `themes/andreaslop/` and `VITE_THEME`/`VITE_DEFAULT_LANGUAGE`, C6 CMS CI/CD (per-client admin build, publish, deploy, `wwwroot/web/` kept outside the swapped release).
|
||||
- **Requirements**: FR-1, FR-2, FR-4, FR-5, FR-6, FR-7, FR-10 (configuration part), FR-11, NFR-1 (setup flow exposure, logging), NFR-5, NFR-6 (client tests), NFR-7.
|
||||
- **Construction stages**: Functional Design (module minimum, setup flow), NFR Requirements, NFR Design, Infrastructure Design (database for the new host, ports, release layout, CI matrix), Code Generation.
|
||||
- **Done when**: the host starts on test with its own database, `/admin` shows Andrea's theme in Dutch and allows first-admin setup and login, `/api/v1/System/capabilities` lists no `Offerings`, `/health` is green, and `Api.SlpSoftware` still builds and deploys unchanged.
|
||||
- **Code location**: `src/SlpModularCms.Api.AndreaSlopFotografie`, `frontend/themes/andreaslop`, `.gitea/workflows`, solution placement under **Clients** per the CMS repo's `AGENTS.md`.
|
||||
|
||||
## U3 `site-delivery` (WEB repo, built by this session)
|
||||
|
||||
- **Purpose**: Get the prerendered site onto Andrea's host and prove it behaves like the old static deployment.
|
||||
- **Components**: C7 delivery job in the web CI, C8 extended `web/deploy/verify-deployment.sh` (exact CSP, canonical redirects, `404.html` status, cache and `noindex` on test, admin and API reachable), retiring the static nginx test site after proof.
|
||||
- **Requirements**: FR-12, FR-13, FR-14, FR-10 (drift guard), NFR-2, NFR-3 (Lighthouse not lower), NFR-5.
|
||||
- **Construction stages**: Infrastructure Design, Code Generation. (Functional Design, NFR Requirements and NFR Design are skipped as planned.)
|
||||
- **Done when**: a web CI run on the target branch delivers the build to the test host; verification passes; the static test site is retired.
|
||||
- **Code location**: this repo's CI workflow and `web/deploy/`. No change to `web/src`. Starts after the Testimonials feature has merged or overlap is ruled out.
|
||||
|
||||
## Cross-cutting
|
||||
|
||||
- **FR-15** (collaboration with the CMS session) spans all units. One brief covers U1 and U2 (owner decision); the CMS session sequences them and reports back after U1. The brief lives in this feature's folder and a copy is placed in the CMS repo's AIDLC folder.
|
||||
- **Build and Test** (phase level) covers the proof across all three units on test.
|
||||
- **Operations** (Deployment, Monitoring, Production Readiness) covers the new host on test.
|
||||
- **Code organisation**: brownfield; no new top-level directories in this repo. Documentation only under `aidlc-docs/features/cms-api-foundation/`; the CMS session records its approved design and hand-back under `construction/cms-host/` here.
|
||||
Reference in New Issue
Block a user