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:
+46
@@ -0,0 +1,46 @@
|
||||
# Application Design Plan - andreaslop-site-hosting
|
||||
|
||||
## Steps
|
||||
- [x] Analyse requirements and host code (done: CmsHost, StaticContentExtensions, CspPolicyCatalog, SecurityHeadersOptions, SetupController)
|
||||
- [x] Collect answers to the design questions below
|
||||
- [x] Generate components.md
|
||||
- [x] Generate component-methods.md
|
||||
- [x] Generate services.md
|
||||
- [x] Generate component-dependency.md
|
||||
- [x] Generate application-design.md (consolidated)
|
||||
- [x] Validate completeness and consistency (security baseline / PBT applicability)
|
||||
|
||||
## Facts from the code that shape the questions
|
||||
- `SecurityHeadersOptions.AllowedConnectOrigins` is applied to **both** `Strict` and `Relaxed`. If the Umami and Sentry origins were put there for Andrea's site, the admin (`/admin`, `/api/v1`, under `Strict`) would get them too. `AllowedScriptOrigins` is only used by `Relaxed` today.
|
||||
- Linux file systems are case-sensitive, and all page files are lowercase. A request `/Over-Mij` therefore resolves to a known page exactly when `over-mij.html` exists. A cached "known page set" is not strictly needed: a file-exists predicate on the lowercased name gives the same nginx behaviour.
|
||||
- `UseHttpsRedirection` is a no-op when the host listens on plain HTTP only without an HTTPS port configured; the proxy Pi talks HTTP to the app. There is no forwarded-headers handling in `CmsHost` today. To be verified in NFR Design against the SlpSoftware deployment.
|
||||
- `SetupController` (`GET /Setup/status`, `POST /Setup/owner`) has no protection other than "system not yet initialised". The admin setup page posts to it.
|
||||
|
||||
## Design Questions
|
||||
|
||||
### Question 1: Origins for the StrictSite policy
|
||||
Where do the Umami script origin and the Sentry connect origins for the website live?
|
||||
|
||||
- A) New separate lists in `SecurityHeaders` (for example `AllowedSiteScriptOrigins`, `AllowedSiteConnectOrigins`) used only by `StrictSite`; the admin policies stay exactly as strict as today (recommended)
|
||||
- B) Reuse the existing `AllowedScriptOrigins` / `AllowedConnectOrigins`; accept that `Strict` (admin and API) then also lists the Sentry ingest origin in `connect-src`
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (RELAYED by CMS & API on Bryan's behalf; confirmed when Bryan approves the design)
|
||||
|
||||
### Question 2: How the host decides a page is "known"
|
||||
nginx canonicalises (301) only known pages. How should the host decide this?
|
||||
|
||||
- A) Per request, a file-exists check on the lowercased name (`<name>.html`, or `<name>/index.html`); no cache, so a site delivered in place (symlink variant, rsync) is always current. The pure resolver takes the check as a predicate (recommended)
|
||||
- B) A snapshot of the known pages built at startup and refreshed on a short timer or file watcher
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (RELAYED by CMS & API on Bryan's behalf; confirmed when Bryan approves the design)
|
||||
|
||||
### Question 3: First-admin setup token in the admin
|
||||
The setup token protects `POST /Setup/owner`. How does the person doing the first setup supply it?
|
||||
|
||||
- A) The setup page shows a "setup token" field, but only when the server says one is required (`GET /Setup/status` returns `tokenRequired`); the token is sent in a request header; small frontend change, no change when no token is configured (recommended)
|
||||
- B) No frontend change: the token is sent only as a header by a direct API call (for example curl), the setup page stays as it is
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (RELAYED by CMS & API on Bryan's behalf; confirmed when Bryan approves the design)
|
||||
@@ -0,0 +1,170 @@
|
||||
# Execution Plan - andreaslop-site-hosting
|
||||
|
||||
## Detailed Analysis Summary
|
||||
|
||||
### Transformation Scope (Brownfield)
|
||||
- **Type**: Extension of the shared host (`SlpModularCms.Core`) plus one new deployable client, an admin theming mechanism and CI/CD for a second deployment target. No rewrite; existing clients (`Api`, `Api.SlpSoftware`) must behave exactly as before.
|
||||
- **Primary changes**: (U1) `WebsiteMode.PrerenderedPages` with nginx-parity serving, `StrictSite` CSP policy, `Website:NoIndex`; (U2) client `SlpModularCms.Api.AndreaSlopFotografie`, admin theme via `VITE_THEME`/`VITE_DEFAULT_LANGUAGE`, optional first-admin setup token, CI/CD to the test Pi.
|
||||
- **Related components**: Core (`CmsHost`, `CmsHostOptions`, `StaticContentExtensions`, `CspPolicyCatalog`, security headers), Modules.Identity (setup token), frontend (theme tokens, build), `.gitea/workflows/*`, README / `WEBSITE_WORKSPACE.md`.
|
||||
|
||||
### Change Impact Assessment
|
||||
- **User-facing changes**: Yes - public website served by the host (visitor), themed Dutch admin (site owner).
|
||||
- **Structural changes**: Yes - new client project, new options/middleware in Core.
|
||||
- **Data model changes**: No new entities. New database instance per site (`AndreaSlopFotografieTest`); existing migrations apply. Setup token is configuration, not data.
|
||||
- **API changes**: Setup endpoint gains an optional token requirement (only when configured). No other API change.
|
||||
- **NFR impact**: Yes - Security Baseline (blocking), PBT partial, performance of per-request path resolution, proxy/HTTP 1.0 behaviour.
|
||||
|
||||
### Component Relationships
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
core["SlpModularCms.Core<br/>(CmsHost, StaticContent, CSP catalog)"]
|
||||
api["SlpModularCms.Api"]
|
||||
slp["SlpModularCms.Api.SlpSoftware"]
|
||||
andrea["SlpModularCms.Api.AndreaSlopFotografie<br/>(new client, U2)"]
|
||||
ident["Modules.Identity<br/>(setup token)"]
|
||||
avail["Modules.Availability"]
|
||||
fe["frontend<br/>(theme per site)"]
|
||||
ci["Gitea workflows<br/>(CI + deploy-scp)"]
|
||||
pi["Test Pi<br/>(port 5200)"]
|
||||
|
||||
core -->|"unchanged behaviour"| api
|
||||
core -->|"unchanged behaviour"| slp
|
||||
core -->|"PrerenderedPages + StrictSite (U1)"| andrea
|
||||
andrea --> ident
|
||||
andrea -.->|"only if required"| avail
|
||||
fe -->|"VITE_THEME=andreaslop"| andrea
|
||||
ci -->|"build + deploy (test only)"| andrea
|
||||
andrea --> pi
|
||||
|
||||
classDef shared fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef existing fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef new fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef ext fill:#d6bcfa,stroke:#553c9a,stroke-width:1px,color:#000;
|
||||
class core shared;
|
||||
class api,slp,ident,avail,fe existing;
|
||||
class andrea new;
|
||||
class ci,pi ext;
|
||||
```
|
||||
|
||||
Text alternative: Core serves all clients; the new Andrea client uses the new website mode and policy, references Identity (Availability only if needed), gets a themed admin build and is deployed by CI to the test Pi.
|
||||
|
||||
| Component | Change type | Reason | Priority |
|
||||
|---|---|---|---|
|
||||
| Core hosting | Major (additive) | New mode, middleware, policy | Critical |
|
||||
| Api, Api.SlpSoftware | None (regression-guarded) | Must stay unchanged | Critical |
|
||||
| Identity | Minor | Optional setup token | Important |
|
||||
| Frontend | Minor | Theme tokens, language default | Important |
|
||||
| CI/CD | Minor | Per-client admin build, second deploy target | Important |
|
||||
| Docs | Minor | README, WEBSITE_WORKSPACE.md | Important |
|
||||
|
||||
### Risk Assessment
|
||||
- **Risk level**: Medium. Shared host change touches every client (mitigated by default `SpaFallback` and regression tests); public-facing path handling (traversal / open redirect) is security-relevant; deployment on a Pi that is not yet provisioned.
|
||||
- **Rollback complexity**: Easy for code (feature flag by default off); moderate for the Pi (manual steps by Bryan, test only).
|
||||
- **Testing complexity**: Complex (PBT on pure functions, integration tests of the pipeline with a temp website root, theme visual/contrast check, deploy smoke test).
|
||||
|
||||
## Workflow Visualization
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Brief from CMS & API"])
|
||||
|
||||
subgraph INCEPTION["INCEPTION PHASE"]
|
||||
WD["Workspace Detection<br/><b>COMPLETED</b>"]
|
||||
RE["Reverse Engineering<br/><b>SKIP (reuse)</b>"]
|
||||
RA["Requirements Analysis<br/><b>COMPLETED</b>"]
|
||||
US["User Stories<br/><b>SKIP</b>"]
|
||||
WP["Workflow Planning<br/><b>IN PROGRESS</b>"]
|
||||
AD["Application Design<br/><b>EXECUTE</b>"]
|
||||
UG["Units Generation<br/><b>EXECUTE (minimal)</b>"]
|
||||
end
|
||||
|
||||
subgraph CONSTRUCTION["CONSTRUCTION PHASE"]
|
||||
U1["Unit U1 core-site-hosting<br/>FD, NFR Req, NFR Design, Code, per-unit build/test"]
|
||||
H1["Hand-back U1 + wait for go"]
|
||||
U2["Unit U2 andreaslop-client<br/>NFR Req, NFR Design, Infra Design, Code, per-unit build/test"]
|
||||
H2["Hand-back U2"]
|
||||
BT["Build and Test (all units)<br/><b>EXECUTE</b>"]
|
||||
end
|
||||
|
||||
subgraph OPERATIONS["OPERATIONS PHASE"]
|
||||
DS["Deployment Setup<br/><b>EXECUTE</b>"]
|
||||
MS["Monitoring Setup<br/><b>EXECUTE</b>"]
|
||||
PRV["Production Readiness Validation<br/><b>EXECUTE</b>"]
|
||||
end
|
||||
|
||||
Start --> WD --> RE --> RA --> US --> WP --> AD --> UG --> U1 --> H1 --> U2 --> H2 --> BT --> DS --> MS --> PRV --> End(["Complete"])
|
||||
|
||||
style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style RA fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style WP fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style RE fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
|
||||
style US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
|
||||
style AD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style UG fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style U1 fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style U2 fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style H1 fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
|
||||
style H2 fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
|
||||
style DS fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style MS fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style PRV fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
|
||||
style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
|
||||
linkStyle default stroke:#333,stroke-width:2px
|
||||
```
|
||||
|
||||
Text alternative: green = done/always, orange dashed = conditional EXECUTE, grey dashed = SKIP, purple = checkpoints with the requester.
|
||||
|
||||
## Phases to Execute
|
||||
|
||||
### INCEPTION
|
||||
- [x] Workspace Detection (COMPLETED)
|
||||
- [x] Reverse Engineering (SKIPPED - existing `_shared/reverse-engineering/` reused; key host files read directly)
|
||||
- [x] Requirements Analysis (COMPLETED, approved by Bryan)
|
||||
- [x] User Stories (SKIPPED per Q6)
|
||||
- [x] Workflow Planning (IN PROGRESS)
|
||||
- [ ] Application Design - EXECUTE
|
||||
- **Rationale**: New components (WebsiteMode option, path resolver, prerendered-site middleware, StrictSite policy, client project, theme mechanism, setup-token check). The requester expects Bryan's design approval.
|
||||
- [ ] Units Generation - EXECUTE (minimal; no separate Units Planning question round)
|
||||
- **Rationale**: The two units are fixed by the brief. Formalise them (scope, order, dependencies, hand-back gates) in `unit-of-work.md`.
|
||||
|
||||
### CONSTRUCTION (per unit; U2 only after the requester's "go")
|
||||
**U1 core-site-hosting**
|
||||
- [ ] Functional Design - EXECUTE: path-resolution rule table, canonical form, known-page set, 404 and reserved-prefix behaviour, noindex/robots rules.
|
||||
- [ ] NFR Requirements - EXECUTE: security (traversal, open redirect, header completeness), PBT properties (partial mode), performance of lookup, proxy/HTTP 1.0 compatibility.
|
||||
- [ ] NFR Design - EXECUTE (compact): caching of file existence / known-page refresh, middleware ordering, compression scope.
|
||||
- [ ] Infrastructure Design - SKIP: no infrastructure change in U1.
|
||||
- [ ] Code Generation - EXECUTE (plan + generation + automatic per-unit build/test, regression run of `Api`/`Api.SlpSoftware`)
|
||||
- [ ] Hand-back note U1, message to "CMS & API", **wait for go**
|
||||
|
||||
**U2 andreaslop-client**
|
||||
- [ ] Functional Design - SKIP: no new business domain; theme token mapping and client composition are covered by Application Design and requirements.
|
||||
- [ ] NFR Requirements - EXECUTE: setup-token security, secrets handling, contrast/accessibility of the theme, login rate limiting.
|
||||
- [ ] NFR Design - EXECUTE (compact): token check placement, constant-time compare, configuration shape.
|
||||
- [ ] Infrastructure Design - EXECUTE: Pi layout, systemd user unit, env variables, database `AndreaSlopFotografieTest` / user `AndreaSlopFotografie`, ufw rule for port 5200, proxy-Pi route, Gitea secrets, both `wwwroot/web` delivery variants, manual-step list for Bryan; then notify "CMS & API" so the Pi-Main session can draft commands.
|
||||
- [ ] Code Generation - EXECUTE (client, theme, setup token, workflows; per-unit build/test)
|
||||
- [ ] Test deploy - only with Bryan's go in this session, test host only
|
||||
- [ ] Hand-back note U2
|
||||
|
||||
- [ ] Build and Test - EXECUTE (full solution, frontend build per theme, cross-unit integration, smoke checks)
|
||||
|
||||
### OPERATIONS (Operations Configuration = Yes)
|
||||
- [ ] Deployment Setup - EXECUTE
|
||||
- [ ] Monitoring Setup - EXECUTE
|
||||
- [ ] Production Readiness Validation - EXECUTE (for the test environment; production out of scope)
|
||||
|
||||
## Package Change Sequence
|
||||
1. `SlpModularCms.Core` (+ `Core.Tests`) - U1
|
||||
2. `Api` / `Api.SlpSoftware` regression run - U1
|
||||
3. `SlpModularCms.Modules.Identity` (+ tests) - setup token (U2)
|
||||
4. `frontend` theme and build variables - U2
|
||||
5. `SlpModularCms.Api.AndreaSlopFotografie` (+ solution entry under Clients) - U2
|
||||
6. `.gitea/workflows` (CI matrix per client, deploy to test) - U2
|
||||
7. Docs (`README.md`, `WEBSITE_WORKSPACE.md`) - U1 and U2
|
||||
|
||||
## Success Criteria
|
||||
- **Primary goal**: Andrea's prerendered site and a themed Dutch admin served by one SlpModularCms process on the test Pi, with behaviour matching today's nginx and the exact CSP.
|
||||
- **Key deliverables**: WebsiteMode + StrictSite in Core; new client; theme; setup token; CI/CD; hand-back notes; Pi manual-step list.
|
||||
- **Quality gates**: Security Baseline compliance per stage; PBT-02/03/07/08/09 satisfied; `Api` and `Api.SlpSoftware` green and unchanged; per-unit build/test; requester's "go" before U2; Bryan's approval of requirements and design; no push without Bryan's request; no production changes.
|
||||
@@ -0,0 +1,9 @@
|
||||
# Unit of Work Plan - andreaslop-site-hosting
|
||||
|
||||
Decomposition is fixed by the brief and the approved execution plan (two units, U1 then U2, hand-back gate between them). No open decomposition questions: no ambiguity found in story grouping, dependencies, deployment or code organisation (brownfield; structure rules from CLAUDE.md/AGENTS.md apply).
|
||||
|
||||
- [x] Generate `inception/application-design/unit-of-work.md`
|
||||
- [x] Generate `inception/application-design/unit-of-work-dependency.md`
|
||||
- [x] Generate `inception/application-design/unit-of-work-story-map.md` (requirements-to-unit map; User Stories were skipped)
|
||||
- [x] Validate unit boundaries and dependencies
|
||||
- [x] Ensure every requirement is assigned to a unit
|
||||
Reference in New Issue
Block a user