AIDLC-documentatie U2 (NFR, infrastructuur, code generation)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-07 01:16:34 +01:00
co-authored by Claude Sonnet 5.5
parent 88f5d20a78
commit c69ef9188e
16 changed files with 628 additions and 3 deletions
@@ -0,0 +1,51 @@
# Code Generation Plan - andreaslop-client (U2)
Single source of truth for U2 code generation. Brownfield. Application code under `src/` and `frontend/`; workflow under `.gitea/workflows/`; docs summary under `construction/andreaslop-client/code/`. Names follow the ASF convention (see infrastructure-design.md). No push; one local commit per part.
## Unit context
- Implements FR-U2-01..05, NFR-* and P1-P12 (NFR design), infrastructure design (test only).
- Depends on U1 (done): `WebsiteMode.PrerenderedPages`, `StrictSite`, `Website:NoIndex`.
- Shared change (option B) touches `Api`, `Api.SlpSoftware`, `Api.Slave`: opt-in, safe degradation, full regression required.
- Tests needing MariaDB (`Api.Tests`, host regression) are run if a local/Pi DB is reachable; otherwise reported as not runnable.
## Part A - Core: forwarded headers and per-client limiters (P11, P12)
- [x] **A1** `Core/Hosting/ForwardedHeadersOptions` (`ForwardedHeaders:KnownProxies`), validation (unparsable and any-address entries rejected), registration; `UseForwardedHeaders` first in `CmsHost` only when proxies are configured (ForwardLimit 1, XForwardedFor|XForwardedProto, default known proxies cleared).
- [x] **A2** `ClientPartitionKey` + `AddCmsRateLimiting`: per-client-address partitions for `login`, `refresh`, sentry-tunnel, `offerings-public`; fallback key when address unknown. Behaviour with no config is unchanged.
- [x] **A3** Tests: options validation, partition key (incl. PBT: distinct addresses never share a bucket, same address always does), integration via TestServer (spoofed header from untrusted peer ignored; trusted proxy honoured; limiter isolates clients).
- [x] **A4** Build + test Core and all three existing hosts' projects; regression for Api/Api.SlpSoftware/Api.Slave (MariaDB-dependent ones reported). (non-DB suites green; Api.Tests needs MariaDB, run in CI)
## Part B - Identity: setup token (P1-P3, P6)
- [x] **B1** `SetupOptions` (`Identity:Setup:Token`), whitespace-only token = startup error; `ISetupTokenValidator` / `SetupTokenValidator` (SHA-256 + `CryptographicOperations.FixedTimeEquals`, header `X-Setup-Token`).
- [x] **B2** `SetupController`: `[EnableRateLimiting("login")]` on both endpoints; `POST owner` checks token (identical 401 for missing/wrong, no detail); `GET status` returns `initialized` + `tokenRequired`.
- [x] **B3** `SecurityEvents.SetupTokenRejected` (id 5007, `setup_token_rejected`), logged on failed attempts without echoing the token.
- [x] **B4** Tests: validator (examples + PBT: only the exact token passes, any other string fails, no exception), controller (no token configured = today's behaviour; token required; 401 uniformity; event logged), status payload.
- [x] **B5** Build + test `Modules.Identity` and its tests.
## Part C - New client project `SlpModularCms.Api.AndreaSlopFotografie`
- [x] **C1** Project in `src/`, added to the solution under **Clients**; thin `Program.cs` with `CmsHostOptions { WebsiteMode = PrerenderedPages }`; Identity module; Availability module only if required (capabilities must not list `Offerings`).
- [x] **C2** Three-file appsettings per the `dotnet-appsettings` skill (`appsettings.json` without secrets: `SecurityHeaders` `DefaultPolicy=StrictSite` + site Umami/Sentry origins, `Website:NoIndex=true`, JWT issuer/audience, rate limits), `launchSettings` port 5200, publish settings like Api.SlpSoftware.
- [x] **C3** Tests: host regression (capabilities has no `Offerings`, `/health`, website serving from a temp `wwwroot/web`, headers), needs MariaDB like `Api.Tests`. (config tests run; pipeline tests need MariaDB, run in CI)
- [x] **C4** Build + test.
## Part D - Frontend: ASF theme, language, setup token (P9, P10)
- [x] **D1** `frontend/themes/asf/theme.css`: CSS variables only, ASF palette exactly as the website (Q5 = B, no contrast adjustment; trade-off recorded), self-hosted Marcellus/Jost, logo + favicon assets.
- [x] **D2** Vite alias driven by `VITE_THEME` (unset = empty module, today's admin); `VITE_DEFAULT_LANGUAGE` in `i18n/config.ts` (stored choice > env default > browser).
- [x] **D3** Setup page: token field only when `tokenRequired`; sends `X-Setup-Token`; translations nl/en.
- [x] **D4** Vitest: theme alias unset/set, language order, setup page with/without token. Compute below-AA contrast pairs for the hand-back.
- [x] **D5** Frontend lint, type-check, test, build for both default and `VITE_THEME=asf`.
## Part E - CI/CD (P8)
- [x] **E1** `continuous_integration.yaml`: add `publish-asf-test` and `deploy-asf-test`, gated by `vars.ASF_TEST_DEPLOY_ENABLED == 'true'`, reusing `deploy-scp.yaml`; manual box "Deploy ASF test". Existing SlpSoftware jobs, env block and `deploy-scp.yaml` byte-for-byte unchanged (verified by diff). Admin build env: `VITE_THEME=asf`, `VITE_DEFAULT_LANGUAGE=nl`, `VITE_APP_ENV=test`, `VITE_SENTRY_DSN` from `VITE_SENTRY_DSN_ASF`.
- [x] **E2** Validate YAML; confirm via diff that nothing else changed; note the open verification item (Gitea `vars` in job-level `if:`).
## Part F - Documentation and wrap-up
- [x] **F1** Update `README.md`/`AGENTS.md` (+ mirrors `CLAUDE.md`, `.junie/guidelines.md`, `.github/copilot-instructions.md` together) for the new Clients project and the opt-in `ForwardedHeaders` setting; `WEBSITE_WORKSPACE.md` if affected.
- [x] **F2** `construction/andreaslop-client/code/code-summary.md`.
- [x] **F3** Full solution build and all tests; report results honestly.
- [x] **F4** Local commits (code, then docs); no push.
## Deployment artifacts
Workflow jobs (Part E) and appsettings (C2); Pi steps are in `manual-steps-for-bryan.md`. The test deploy itself only happens with Bryan's explicit go.
## Traceability
A -> option B / NFR (proxy awareness); B -> FR-U2-05 (setup token); C -> FR-U2-01/02; D -> FR-U2-03; E -> FR-U2-04; F -> docs.
@@ -0,0 +1,43 @@
# Infrastructure Design Plan - andreaslop-client (U2)
## Steps
- [x] Analyse design artifacts (NFR requirements/design, `pi-inventory-notes.md`, `deploy-scp.yaml`, `continuous_integration.yaml`)
- [x] Collect answers to the questions below
- [x] Generate `infrastructure-design/infrastructure-design.md` (components, Pi layout, env variables, Gitea variables/secrets)
- [x] Generate `infrastructure-design/deployment-architecture.md` (diagrams, deploy sequence)
- [x] Generate `infrastructure-design/manual-steps-for-bryan.md` (complete ordered list, both web-delivery variants)
- [x] Tell "CMS & API" the list is complete so Pi-Main can draft the commands
## Category evaluation
- Deployment environment: on-premise Pis, test only (decided). Pattern copied from SlpSoftware test.
- Compute: one .NET process (~250-300 MB), systemd user unit, port 5200; sizing fits the Pi 4 (decided).
- Storage: MariaDB 10.11 `AndreaSlopFotografieTest` / `AndreaSlopFotografie@localhost` (decided); website files either in the release tree or on `/mnt/storage1` (Question 1).
- Messaging: not applicable.
- Networking: proxy Pi (TLS, certbot) forwards HTTP/1.0 to 192.168.1.102 -> app port 5200; ufw only from the proxy Pi; the proxy block must pass `X-Forwarded-For`/`-Proto` (decided by option B); first-deploy sequence (Question 2).
- Monitoring: `/health`, logs via journald, Sentry (Question 3).
- Shared infrastructure: runner (arm64 label for builds is NOT needed: publish runs on ubuntu-latest with `-r linux-arm64` exactly like SlpSoftware), the SSH deploy secrets `PI_MAIN_*`, the DB backup script (Pi-Main adds the new DB).
## Question 1: How does the website reach `wwwroot/web` on the test host?
Both variants work without restart (U1 looks pages up per request). Which one do we document as THE path?
- A) Symlink: `shared/wwwroot-web` points to `/mnt/storage1/www/html/andreaslop-test`, the folder the existing web deploy already writes to, so the current website pipeline keeps working unchanged (recommended: no change in the website repo; files live on the big disk, not on the SD card)
- B) Direct: the website CI copies its build into `shared/wwwroot-web` on the SD card (needs a change in the website pipeline and its target path)
- X) Other (please describe after [Answer]: tag below)
[Answer]: A (relayed via CMS and API, Bryan): symlink shared/wwwroot-web to /mnt/storage1/www/html/andreaslop-test; website repo deploy unchanged.
## Question 2: Health check and the first deploy
The deploy workflow checks `/health` on the PUBLIC test URL after switching the release. That URL (`test.andreaslop.nl`) still points at the old nginx fallback until you switch the proxy-Pi route, so a first deploy before the switch fails its health check (the new release is then already live on port 5200, only the job is red).
- A) Switch the proxy-Pi route to port 5200 first, then run the first deploy; the test site is down only for the minutes between the switch and the first successful deploy (recommended: simplest, test environment)
- B) Deploy first with the health-check variable pointing to a temporary URL that already reaches port 5200 (extra hostname + certificate work for you), then switch the route
- C) Deploy first, accept one red health check, verify manually on port 5200 from the proxy Pi, then switch the route
- X) Other (please describe after [Answer]: tag below)
[Answer]: A (relayed via CMS and API, Bryan): switch the proxy-Pi route to port 5200 first, then run the first deploy; short downtime accepted; order and nginx fallback revert explicit in the manual steps.
## Question 3: Sentry for the new host and its admin
- A) A new, separate Sentry project for the CMS host and admin, DSNs supplied through `shared/env` (backend `Observability__SentryDsn`) and the Gitea variable `VITE_SENTRY_DSN_ASF` (frontend) (recommended: keeps the website's own Sentry project clean)
- B) Reuse the website's existing Sentry project (same DSN) for host and admin
- C) No Sentry for now (empty DSN is a supported state); add later
- X) Other (please describe after [Answer]: tag below)
[Answer]: B (relayed via CMS and API, Bryan): reuse the website existing Sentry project (same DSN) for host and admin.
@@ -0,0 +1,14 @@
# NFR Design Plan - andreaslop-client (U2)
## Steps
- [x] Analyse NFR requirements (nfr-requirements.md, tech-stack-decisions.md)
- [x] Evaluate question categories; no open questions (justification below)
- [x] Generate `nfr-design/nfr-design-patterns.md`
- [x] Generate `nfr-design/logical-components.md`
## Category evaluation (why no questions)
- Resilience: deploy resilience is inherited from `deploy-scp.yaml` (atomic switch, health check, previous release kept); the new part is only the skip switch (NFR-DEP-02), which has one obvious design.
- Scalability and performance: N/A for U2 (one small instance).
- Security: the token check, limiter and security event follow the answers Q3/Q4 and the existing `SecurityEvents` and rate-limiting mechanisms; placement has one sensible solution.
- Logical components: no new infrastructure; one validator, one controller change, one security event, one CSS theme, two CI jobs.
- Open verification items are listed in `nfr-design-patterns.md` and are settled by tests or the first test deploy.
@@ -0,0 +1,57 @@
# NFR Requirements Plan - andreaslop-client (U2)
U2 Functional Design is skipped (execution plan: no new business domain).
## Steps
- [x] Analyse unit context (requirements FR-U2-01..08, application design C1/C5/C6/C7, existing `continuous_integration.yaml`, `deploy-scp.yaml`, `SetupController`)
- [x] Collect answers to the questions below
- [x] Generate `nfr-requirements/nfr-requirements.md` and `tech-stack-decisions.md`
- [x] Security Baseline and PBT applicability (tabulated in the artifacts)
## Findings from the existing code that shape the questions
- `continuous_integration.yaml` deploys `Api.SlpSoftware` to its test host **automatically on every push to master** and has a separate opt-in production deploy. The reusable `deploy-scp.yaml` already does what Andrea needs (timestamped release, `shared/wwwroot-web` symlink, atomic `current` switch, health check), so both website-delivery variants only differ in what `shared/wwwroot-web` is.
- `POST /Setup/owner` and `GET /Setup/status` are anonymous and have **no rate limiter**; only `/Auth/login` (`login` policy: 5 per 60 s) and refresh are limited.
- The shared admin frontend is built once per publish job with Vite variables; it has `dev:slpsoftware` modes and a `useTheme` hook (light/dark).
## Pre-filled assumptions
- Scale/availability: one small instance on the test Pi; no HA; rollback = previous release kept by `deploy-scp.yaml`.
- Secrets (DB password, JWT secret, setup token, Sentry DSN) only in `shared/env` on the Pi and Gitea secrets/variables, never in the repository.
- Tech stack: no new packages; theme is plain CSS variables; token comparison via `CryptographicOperations.FixedTimeEquals`.
## Question 1: When does the ASF test deploy run?
- A) Only when someone starts the workflow manually and ticks a new box "Deploy ASF test" (recommended: a merge to master never touches Andrea's site by surprise; test only)
- B) Automatically on every push to master, like `Api.SlpSoftware`, plus the manual box
- X) Other (please describe after [Answer]: tag below)
[Answer]: B-ish (relayed via CMS and API, Bryan: Zelfde als nu): automatic test deploy on every push to master like Api.SlpSoftware, plus the manual box. Test only. Must skip cleanly while Andrea deploy variables and secrets are unset.
## Question 2: How do the pipelines relate?
- A) Add separate jobs for the Andrea client (build its admin with its theme, publish its project, call the existing `deploy-scp.yaml`); the `Api.SlpSoftware` jobs stay byte-for-byte as they are (recommended: zero risk for the existing deploy)
- B) Turn the existing publish job into a matrix over both clients (less duplication, but changes the working SlpSoftware pipeline)
- X) Other (please describe after [Answer]: tag below)
[Answer]: A (relayed via CMS and API)
## Question 3: Rate limiting for the first-admin setup endpoints
`/Setup/owner` and `/Setup/status` have no limiter today. With the optional setup token a stranger could still guess the token.
- A) Put both setup endpoints under the existing `login` limiter policy (5 per 60 s), and log failed token attempts as a security event (recommended)
- B) A new, separate `setup` limiter policy with its own settings
- C) No limiter, only the token
- X) Other (please describe after [Answer]: tag below)
[Answer]: A (relayed via CMS and API)
## Question 4: Setup token on the test instance
- A) Required on test (set in `shared/env`); the token is only needed until the first administrator exists, and it can be removed from `shared/env` afterwards (recommended)
- B) Optional on test (not set); the setup page is open until the first admin is created
- X) Other (please describe after [Answer]: tag below)
[Answer]: A (relayed via CMS and API)
## Question 5: Theme accessibility target
The theme maps Andrea's brand colours onto the admin's design tokens.
- A) Text and interactive elements must reach WCAG AA contrast (4.5:1 text, 3:1 large text and UI); where the brand colour fails, the admin uses a darker/lighter variant of it (recommended)
- B) Use the brand colours exactly as the website does, without a contrast check
- X) Other (please describe after [Answer]: tag below)
[Answer]: B (relayed via CMS and API, Bryan explicit choice): brand colours exactly as the website, no contrast check. Trade-off recorded in nfr-requirements.md.