Files

10 KiB

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

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=asf"| 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

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

  • Workspace Detection (COMPLETED)
  • Reverse Engineering (SKIPPED - existing _shared/reverse-engineering/ reused; key host files read directly)
  • Requirements Analysis (COMPLETED, approved by Bryan)
  • User Stories (SKIPPED per Q6)
  • 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.