slp-modular-cms/aidlc-docs/features/gitea-deployment-workflow/inception/plans/execution-plan.md

Execution Plan — Gitea Deployment Workflow

Feature: gitea-deployment-workflow Branch: feature/gitea-deployment-workflow Date: 2026-07-27

---

1. Detailed Analysis Summary

Transformation Scope

• Transformation Type: Infrastructure and operations transformation with supporting application changes. This is not a refactor of business logic — it introduces a deployment capability that does not exist today (no .gitea/ directory) and changes how the application is hosted, configured and observed.
• Primary Changes:
  1. New CI/CD pipeline (two workflow files) where none exists.
  2. A change to the hosting contract: the public website moves from wwwroot/ to wwwroot/web/, altering how Program.cs serves static content.
  3. New cross-cutting application concerns: health checks, HTTP security headers, structured error/log reporting.
  4. Durability changes: automatic Core migrations and a database-backed Data Protection key ring.
  5. Deployment-model change: from manual publish to an atomic release-directory switch with a retained previous release.
• Related Components: SlpModularCms.Api (Program.cs, .csproj), SlpModularCms.Core (Data Protection, health checks, security headers, logging), SlpModularCms.Modules.Availability (bypass list), frontend/ (config, Sentry, Umami, lint), plus new .gitea/workflows/ and documentation.
• No infrastructure-as-code exists (no CDK, Terraform, CloudFormation, Docker). Host setup is documented procedure, not code — a direct consequence of NFR-01 (no server configuration).

Change Impact Assessment

Area	Impact	Description
User-facing changes	Indirect, yes	No new features for CMS users. But the public website's URL structure is unchanged while its storage location changes (wwwroot/ → wwwroot/web/), and a CSP begins applying to pages that previously had none. A too-strict CSP would visibly break a customer website.
Structural changes	Yes	Static-file serving is remounted; new middleware enters the pipeline; a new endpoint (/health) is added outside /api/v1; the availability bypass list grows.
Data model changes	Yes, additive	Data Protection key storage moves into the database, requiring a keys table and a DbContext implementing IDataProtectionKeyContext — a new migration. No existing entity changes.
API changes	Minimal, additive	One new non-versioned endpoint /health. No change to any /api/v1 contract. frontend's API base URL becomes same-origin by default, which changes request URLs the SPA emits but not the endpoints themselves.
NFR impact	Substantial	Security (headers, CSP, alerting), reliability (atomic switch, rollback, backup), observability (Sentry, Umami, UptimeRobot), and deployment reproducibility are all new or materially changed. This is where most of the feature's substance lives.

Component Relationships

• Primary Component: SlpModularCms.Api — the deployable host and the only place where all three surfaces meet.
• Shared Components: SlpModularCms.Core — receives health-check registration, security-headers middleware, Data Protection configuration and logging setup, because both host projects must inherit them.
• Dependent Components: SlpModularCms.Api.Slave — inherits every Core change automatically. It must keep working, and it is deliberately excluded from deployment (local-only, no test project).
• Modified Module: SlpModularCms.Modules.Availability — _bypassPrefixes must include /health.
• Frontend Component: frontend/ — config, Sentry, Umami, lint fixes. Coupled to the backend at build time through the publish target.
• Supporting Components (new): .gitea/workflows/, documentation, and external services (Sentry, Umami, UptimeRobot).

Component	Change Type	Change Reason	Priority
SlpModularCms.Api / Program.cs	Major	Static-file remount, health endpoint, middleware order, migrations	Critical
SlpModularCms.Core	Minor (additive)	Health checks, security headers, Data Protection, logging	Critical
SlpModularCms.Modules.Availability	Configuration-only	/health bypass	Critical
SlpModularCms.Api.Slave	None (inherits)	Must not regress	Important
frontend/	Minor	Same-origin config, Sentry, Umami, lint fixes	Critical
.gitea/workflows/	New	The feature's core deliverable	Critical
*.csproj (packages)	Minor	Pin vulnerable packages, add Sentry / health-check / Data Protection packages	Critical
Documentation	New + updates	Website contract, README, operations artifacts	Important

Risk Assessment

• Risk Level: High
• Rollback Complexity: Moderate
• Testing Complexity: Complex

Why High rather than Medium — three failure modes are destructive and silent:

1. Destroying a customer's public website. An atomic release switch that carries wwwroot/web/ inside the swapped directory discards the customer's site on every deploy (ASM-01). Data loss, not a bug.
2. Silently breaking master↔slave trust. Losing the Data Protection key ring makes stored slave API keys undecryptable. The symptom looks like a network fault, so it would be misdiagnosed. FR-12 prevents it — but only if implemented before the first atomic switch.
3. Automatic migrations on startup against production. FR-11 makes deployment self-contained, and consequently makes a bad migration run automatically with no human gate. This is why FR-20 (pre-deploy backup) and forward-compatible migrations are not optional extras.

Additional risk factors: the deploy path cannot be fully tested in CI — it needs the actual Pi, SSH credentials and a database; and a CSP is a class of change that breaks things only in a real browser, on pages this repository does not own.

Mitigations built into the plan: durability changes (Unit 2) land before any deploy workflow (Unit 6); the CSP starts from a known-origin allowlist with the public website deliberately more permissive (D-31); and quality-gate prerequisites (Unit 1) land first so the blocking gates are meaningful rather than immediately red.

---

2. Workflow Visualization

flowchart TD
    Start(["User Request"])

    subgraph INCEPTION["🔵 INCEPTION PHASE"]
        WD["Workspace Detection<br/><b>COMPLETED</b>"]
        RE["Reverse Engineering<br/><b>COMPLETED</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</b>"]
    end

    subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"]
        FD["Functional Design<br/><b>EXECUTE per unit</b>"]
        NFRA["NFR Requirements<br/><b>SKIP</b>"]
        NFRD["NFR Design<br/><b>EXECUTE per unit</b>"]
        ID["Infrastructure Design<br/><b>EXECUTE per unit</b>"]
        CG["Code Generation<br/>Planning plus Generation<br/><b>EXECUTE</b>"]
        BT["Build and Test<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
    WD --> RE
    RE --> RA
    RA --> WP
    WP --> AD
    AD --> UG
    UG --> FD
    FD --> NFRD
    NFRD --> ID
    ID --> CG
    CG --> BT
    BT --> DS
    DS --> MS
    MS --> PRV
    PRV --> End(["Complete"])

    style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
    style RE 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 CG fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
    style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
    style US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
    style NFRA 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 FD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
    style NFRD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
    style ID fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,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 INCEPTION fill:#BBDEFB,stroke:#1565C0,stroke-width:3px,color:#000
    style CONSTRUCTION fill:#C8E6C9,stroke:#2E7D32,stroke-width:3px,color:#000
    style OPERATIONS fill:#FFF59D,stroke:#F57F17,stroke-width:3px,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: Inception is complete except Application Design and Units Generation which will execute; User Stories is skipped. Construction runs Functional Design, NFR Design and Infrastructure Design per unit (NFR Requirements skipped), then Code Generation and Build and Test. All three Operations stages execute.

---

3. Phases to Execute

🔵 INCEPTION PHASE

• Workspace Detection — COMPLETED
• Reverse Engineering — COMPLETED (full rerun, all 8 shared artifacts, verified by executing build/test/lint)
• Requirements Analysis — COMPLETED (23 FRs, 10 NFRs, 32 decisions, 2 question rounds)
• User Stories — SKIP
  • Rationale: This is infrastructure and operations work. It introduces no new end-user functionality, no new persona, and no user journey. The only user-visible effects are a storage-location change and a CSP, both of which are already captured as requirements with acceptance-relevant detail (FR-07, FR-08, FR-18, FR-09). Personas here would be "the developer deploying" and "the website builder consuming the contract" — the latter is properly served by FR-09's documented contract, not by a story. Offered explicitly at Requirements Analysis approval and not requested.
• [~] Workflow Planning — IN PROGRESS (this document)
• Application Design — EXECUTE
  • Rationale: New cross-cutting components genuinely need placement decisions that are not obvious. Where do health checks, security headers and Data Protection registration live — Core (inherited by both hosts, including the Slave) or Api (host-specific)? Getting this wrong either breaks the Slave or duplicates code. Static-file serving must be redesigned for two mounts with two fallbacks and correct ordering relative to the availability gate. The CSP needs a path-scoping mechanism that does not exist yet. And the deploy transport needs an interface that admits FTPS later without restructuring (NFR-09). These are component-boundary and service-layer decisions — exactly this stage's purpose.
• Units Generation — EXECUTE
  • Rationale: The work spans application code, frontend code, two workflow files, package changes and documentation, with a mandatory ordering constraint: durability changes must land before the first automated deploy, and quality-gate fixes must land before blocking gates are switched on. Sequencing this is load-bearing, not bookkeeping. Seven units are proposed in § 5.

🟢 CONSTRUCTION PHASE

• Functional Design — EXECUTE for units 2, 3, 4; SKIP for units 1, 5, 6, 7
  • Rationale: Units 2, 3 and 4 contain real behavioural logic that needs designing before coding — static-file resolution and fallback precedence, migration-at-startup failure behaviour, CSP composition per path, and what a "security-relevant event" is for alerting. Units 1 (lint fixes, package pins), 5 and 6 (declarative YAML) and 7 (documentation) have no business logic to design; a design document there would restate the requirement.
• NFR Requirements — SKIP (all units)
  • Rationale: NFRs are already captured comprehensively and with traceability in requirements.md § 5 (NFR-01…10) and § 6 (full SECURITY-01…15 assessment with four documented deviations). The tech stack is fixed and unchanged. Re-deriving NFRs per unit would duplicate an artifact that already exists at higher quality than a per-unit restatement would produce.
• NFR Design — EXECUTE for units 3 and 4; SKIP for units 1, 2, 5, 6, 7
  • Rationale, including a deliberate deviation: The workflow's default is that NFR Design is skipped when NFR Requirements is skipped. I am overriding that coupling for two units, because for them the NFR is the deliverable: Unit 3 implements SECURITY-04 (how a CSP is composed and path-scoped, how HSTS interacts with the hosting proxy) and Unit 4 implements SECURITY-03 and SECURITY-14 (structured-logging shape, correlation ID per OPEN-01, which events warrant alerting, PII exclusion). Those are pattern decisions, not requirement decisions — so skipping the requirements stage while designing the patterns is the correct split here, not an oversight. For all other units the existing NFRs need no new pattern work.
• Infrastructure Design — EXECUTE for units 6 and 7; SKIP for units 1, 2, 3, 4, 5
  • Rationale: Unit 6 is where the host layout is decided — release-directory scheme, where wwwroot/web/ lives so ASM-01 holds, the symlink or mount strategy, process restart, database backup placement, and the transport abstraction. Unit 7's website contract depends on that layout being settled. This is genuine infrastructure design even though it produces documented procedure rather than IaC (NFR-01 forbids server configuration, so there is nothing to codify). Skipped elsewhere: those units change application code and CI definitions, not infrastructure.
• Code Generation — EXECUTE (always, per unit)
  • Rationale: Implementation planning and code generation are needed for all seven units. Each unit is built and its own tests run before its completion message.
• Build and Test — EXECUTE (always)
  • Rationale: Full cross-unit build plus everything that only appears once units are combined — middleware ordering with the new security headers and health endpoint, the Slave host still starting correctly, the frontend building against the same-origin config, and the publish target producing the expected wwwroot layout.

🟡 OPERATIONS PHASE

• Deployment Setup — EXECUTE
• Monitoring Setup — EXECUTE
• Production Readiness Validation — EXECUTE
  • Rationale: ## Operations Configuration = Yes, decided at Requirements Analysis. For this feature Operations is the centre of gravity, not an afterthought: FR-17 (UptimeRobot monitors), FR-19 (Sentry alert rules), FR-20 (pre-deploy database backup) and FR-23 (deployment, host-setup and rollback documentation, including the FTPS switch path) are all delivered here. Production Readiness Validation will also run the dotnet-appsettings compliance gate, which is directly relevant given D-16 (host environment variables) and the placeholder values in appsettings.json.

---

4. Multi-Module Coordination

Module Update Strategy

• Update Approach: Sequential with two parallelisable pairs.
• Critical Path: SlpModularCms.Core → SlpModularCms.Api → .gitea/workflows/. Core carries the shared cross-cutting registrations; the Api host composes them and defines serving; the workflows can only deploy something that exists and is durable.
• Coordination Points:
  • Core ↔ Api.Slave: every Core change is inherited by the Slave host. The Slave must still start and serve; it has no test project, so this is verified at Build and Test by starting it.
  • Core ↔ Modules.Availability: the /health bypass must land in the same unit as the health endpoint, or /health returns 503 on a disabled instance — the exact conflation the user corrected.
  • Api ↔ frontend: coupled bidirectionally — the SPA calls the API at runtime, and the API's publish target builds the SPA. A same-origin config change (Unit 4) and the wwwroot remount (Unit 2) must agree on where /admin is served from.
  • Package pinning (Unit 1) touches multiple .csproj files and must not conflict with the new packages added in Units 2, 3 and 4.
• Testing Checkpoints: after each unit (automatic per-unit build + test), plus a full-solution checkpoint at Build and Test that additionally starts both hosts and verifies the publish output layout.
• Rollback Strategy (mid-sequence): each unit is a self-contained commit on feature/gitea-deployment-workflow. Units 1–4 are revertible independently. Units 5 and 6 add new files only (.gitea/) and are revertible by deletion. Nothing is deployed to any environment until Unit 6 is complete and explicitly triggered, so a mid-sequence failure cannot affect a running environment.

Per-Module Detail

Module	Priority	Depends on	Depended on by	Change Scope
SlpModularCms.Core	Must-update-first	—	Both hosts, all modules	Minor (additive)
SlpModularCms.Api	Must-update-first	Core	Deployment	Major
SlpModularCms.Modules.Availability	Must-update-with-Core	Core	Both hosts	Patch (bypass list)
SlpModularCms.Api.Slave	Can-update-later (verify only)	Core	—	None (inherits)
frontend	Must-update-before-CI	Api (same-origin contract)	Api publish target	Minor
.gitea/workflows/	Update-last	Everything above	—	New
Documentation	Update-last	Infrastructure Design	—	New + updates

---

5. Proposed Unit Sequence

Final unit definitions are produced by Units Generation; this is the sequence the plan is built around, with the ordering constraints that make it non-arbitrary.

#	Unit	Delivers	Why here
1	Quality Gate Prerequisites	Fix 5 lint errors (FR-21); pin Microsoft.OpenApi and System.Security.Cryptography.Xml (FR-22)	Blocking gates are switched on in Unit 5. If this does not land first, the pipeline is red on arrival and the gates get disabled "temporarily". Independent of everything else, so it costs nothing to do first.
2	Hosting Layout & Data Durability	wwwroot/web/ remount and dual SPA fallbacks (FR-07, FR-08); /health + bypass (FR-10); automatic Core migrations (FR-11); PersistKeysToDbContext (FR-12)	Must precede any automated deploy. The key ring and the wwwroot split are exactly what make an atomic switch non-destructive; deploying first and fixing after means the first deploy is the dangerous one.
3	HTTP Security Headers & CSP	Security-headers middleware, path-scoped CSP (FR-18)	Needs Unit 2's final path layout to scope the CSP. Precedes Unit 4 so the CSP mechanism exists when Umami and Sentry origins need allowing.
4	Observability Integration	Sentry backend + frontend (FR-14, FR-15); structured logging (D-20, OPEN-01); Umami (FR-16); same-origin SPA config (FR-13)	Adds the external origins that Unit 3's CSP must permit, and the environment-tagged build variables that Unit 5's two builds must supply.
5	CI Workflow	continuous_integration.yaml: triggers, six blocking gates, two environment-specific builds, artifacts (FR-01, FR-05)	Gates are meaningful only after Unit 1; the two builds need Unit 4's variables.
6	Deploy Workflow	deploy.yaml: reusable, transport-abstracted, atomic switch, restart, retained previous release, backup hook (FR-02, FR-03, FR-04, FR-06, FR-20)	Last executable piece; depends on everything above being durable and buildable.
7	Repository Documentation	Website workspace contract (FR-09); README updates for the new wwwroot layout and health endpoint; .env.example updates	Depends on Unit 6's settled host layout. Operations-facing documents (deployment instructions, rollback plan, monitoring setup, readiness checklist) are produced in the Operations phase, not here.

---

6. Timeline

• Total stages to execute: 12 (2 remaining Inception + 7 Construction stage-instances across units + Build and Test + 3 Operations)
• Per-unit Construction stage-instances: Functional Design ×3, NFR Design ×2, Infrastructure Design ×2, Code Generation ×7
• Estimated duration: not estimated in wall-clock time. Progress is gated on user approval at every stage boundary, and three items depend on external systems outside this workflow's control: Sentry project and alert-rule creation, Umami website entries, and UptimeRobot monitors. Those are host/service setup steps documented in Operations, not code.

---

7. Success Criteria

Primary Goal

A push to master builds, tests and deploys the CMS to the test environment without manual steps, and production can be deployed by one deliberate action — on hosting where no server configuration is possible, and without ever endangering the customer's public website, the database, or master↔slave trust.

Key Deliverables

1. .gitea/workflows/continuous_integration.yaml and .gitea/workflows/deploy.yaml
2. wwwroot/admin/ + wwwroot/web/ serving, with wwwroot/web/ outside the swapped release directory (ASM-01)
3. /health liveness endpoint, on the availability bypass list, never conflated with domain endpoints
4. Sentry on both sides, Umami on both frontends, UptimeRobot monitors for /health, / and /admin
5. HTTP security-headers middleware with a path-scoped CSP
6. Database-backed Data Protection key ring and automatic Core migrations
7. Website workspace contract, deployment instructions, rollback plan, monitoring setup, production readiness checklist
8. A green pipeline: lint clean, no vulnerable packages, all tests passing

Quality Gates

• dotnet build -c Release: 0 errors
• dotnet test: all backend tests pass (219 at baseline, plus new tests)
• dotnet list package --vulnerable --include-transitive: no advisories
• pnpm run build: succeeds (includes tsc -b)
• pnpm test: all frontend tests pass (213 at baseline, plus new tests)
• pnpm run lint and pnpm run format:check: clean
• No blocking Security Baseline findings at any stage

Integration Readiness

• Both hosts start successfully — SlpModularCms.Api and SlpModularCms.Api.Slave, the latter having no test project and therefore verified by starting it
• dotnet publish produces the expected wwwroot layout with the admin SPA in place
• Middleware ordering verified: exception handler → rate limiter → HTTPS redirect → security headers → static files → CORS → availability gate → auth → endpoints, with /health reachable while the instance is switched off
• The availability gate still blocks /api/v1 and /admin when disabled, and the public website still serves — the pre-existing behaviour recorded in architecture.md, deliberately unchanged

Operational Readiness

• A deploy can be rolled back by redeploying the retained previous release without a rebuild
• A production deploy is preceded by a verifiable database backup
• After a deploy it is determinable, without host access, that the app is alive, whether it is erroring, and whether all expected modules loaded — the last point mattering because ModuleOrchestrator logs rather than throws on module load failure

---

8. Carried-Forward Items

ID	Item	Handled at
ASM-01	wwwroot/web/ must live outside the swapped release directory	Infrastructure Design, Unit 6 — must be confirmed there
OPEN-01	Correlation/request ID mechanism (SECURITY-03)	NFR Design, Unit 4
OPEN-02	IsAdminBypass reads the JWT without validating its signature — pre-existing, needs an owner	Recommend tech-debt-backlog; decide at Application Design whether to fold in
OPEN-03	Exact patched versions for the two vulnerable packages	Code Generation, Unit 1
OPEN-04	When FTPS is actually built	Deferred by design (D-02)
DEV-01…04	Four accepted security deviations	Re-confirmed at Production Readiness Validation