# Execution Plan: hero-module ## Detailed Analysis Summary ### Transformation Scope (Brownfield) - **Transformation Type**: Single new module plus extensions in Core (media serving, host injection) and the admin frontend; a small CI change. - **Primary Changes**: New `SlpModularCms.Modules.Hero` (+ Tests); image pipeline (validation, metadata stripping, variants, focus/crop); media serving with content-hash addresses; hero injection markers in the host (`HtmlMarkerEditor` / `HtmlMarkerInjector`, preload in the head, `hero` key in `#cms-data`); admin screens; seed script; release-branch condition on the SLP production jobs. - **Related Components**: `SlpModularCms.Core` (Hosting/Website, rate limiting, texts), `SlpModularCms.Api` (master composition), `Api.SlpSoftware`, `Api.AndreaSlopFotografie` (module reference and committed defaults, `SiteContractTests`), `frontend/` (admin), `.gitea/workflows/continuous_integration.yaml`, `scripts/`, `openapi/slpsoftware.v1.json`, docs. The websites (SLS, ASF) change on their side. ### Change Impact Assessment - **User-facing changes**: Yes. The hero of both websites is rendered from CMS content; the admin gets a Hero screen; the public pages change when the sites adopt the markers. - **Structural changes**: Yes. A new module, a new media-serving path and new injection parts. - **Data model changes**: Yes. New tables (hero, slides, images/variants) and an EF migration. - **API changes**: Yes. New public `GET /api/v1/hero`, new management endpoints, new media route; no change to existing contracts (NFR-08). - **NFR impact**: Yes. LCP, upload safety (decompression bombs, memory), platform support (win-x64, linux-arm64), storage that survives deploys. ### Component Relationships ```mermaid flowchart LR Admin["Admin frontend
(Hero screen)"] Hero["Modules.Hero
(new)"] Core["Core
(media serving, injection, texts)"] Api["Api (master) and site projects"] SLS["SLP Software website"] ASF["ASF website"] CI["CI workflow"] Admin --> Hero Hero --> Core Api --> Hero Core --> SLS Core --> ASF CI -.-> Api classDef new fill:#FFA726,stroke:#E65100,stroke-width:2px,color:#000; classDef exist fill:#BBDEFB,stroke:#1565C0,stroke-width:1px,color:#000; classDef ext fill:#C8E6C9,stroke:#2E7D32,stroke-width:1px,color:#000; class Hero new; class Admin,Core,Api,CI exist; class SLS,ASF ext; ``` Text alternative: the admin talks to the new Hero module; the module uses Core for media and injection; the master and site projects reference it; Core serves both websites. - **Primary Component**: `SlpModularCms.Modules.Hero` (Major, new). - **Shared Components**: `SlpModularCms.Core` (Minor: new injection parts and media route), `frontend/` (Minor: new feature folder). - **Dependent Components**: the two websites (golden files and markers agreed with the ASF and SLS sessions); `Api.*` projects (Configuration-only: module reference). - **Supporting Components**: CI workflow (Minor: release-branch condition), docs and checklist. ### Risk Assessment - **Risk Level**: Medium to High (image processing of untrusted uploads; a native library on several platforms; contract with two sites). - **Rollback Complexity**: Moderate (the module can be switched off per site; the baked hero stays; one migration). - **Testing Complexity**: Complex (image fixtures, platform matrix, golden files for injection, LCP measurement on test hosts). ## Workflow Visualization ```mermaid flowchart TD Start(["User Request"]) subgraph INCEPTION["🔵 INCEPTION PHASE"] WD["Workspace Detection
COMPLETED"] RE["Reverse Engineering
SKIP"] RA["Requirements Analysis
COMPLETED"] US["User Stories
SKIP"] WP["Workflow Planning
IN PROGRESS"] AD["Application Design
EXECUTE"] UG["Units Generation
EXECUTE"] end subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"] FD["Functional Design
EXECUTE"] NFRA["NFR Requirements
EXECUTE"] NFRD["NFR Design
EXECUTE"] ID["Infrastructure Design
CONDITIONAL"] CG["Code Generation
(Planning + Generation)
EXECUTE"] BT["Build and Test
EXECUTE"] end Start --> WD WD --> RA RA --> WP WP --> AD AD --> UG UG --> FD FD --> NFRA NFRA --> NFRD NFRD --> ID ID --> CG CG --> BT BT --> 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 CG fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff 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 NFRA 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 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 Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 style INCEPTION fill:#BBDEFB,stroke:#1565C0,color:#000 style CONSTRUCTION fill:#C8E6C9,stroke:#2E7D32,color:#000 linkStyle default stroke:#333,stroke-width:2px ``` Text alternative: Inception (detection, requirements done; planning in progress; application design and units to execute; reverse engineering and user stories skipped) leads to construction (design stages per unit, code generation, build and test) and ends without an Operations phase. ## Phases to Execute ### 🔵 INCEPTION PHASE - [x] Workspace Detection (COMPLETED) - [x] Reverse Engineering (SKIPPED: targeted review; `_shared/` artifacts exist) - [x] Requirements Analysis (COMPLETED, approved by Bryan 2026-11-16) - [x] User Stories (SKIPPED) - **Rationale**: One persona (the site administrator) plus the two websites as consumers; the requirements already carry the acceptance criteria and the contract is agreed with the two site sessions. - [x] Execution Plan (IN PROGRESS) - [ ] Application Design - EXECUTE - **Rationale**: New module and new Core components (image pipeline, media store, injection parts); public JSON shape, marker names and crop/focus model (A3, A4) and the storage decision (A2) are decided here, with the ASF and SLS sessions. - [ ] Units Generation - EXECUTE - **Rationale**: Several independent pieces (CI condition, image pipeline, module backend, media serving, injection, admin UI, seed and docs) with a dependency order. ### 🟢 CONSTRUCTION PHASE - [ ] Functional Design - EXECUTE (per unit where needed: hero and slide rules, focus/crop model, injection output) - **Rationale**: New data model and business rules (validation of targets, scheduling, slide selection, variant choice). - [ ] NFR Requirements - EXECUTE (image pipeline and injection units) - **Rationale**: Library choice (AVIF, licence, win-x64 and linux-arm64), upload limits, LCP and weight budgets (A1, A6, A7). - [ ] NFR Design - EXECUTE (image pipeline unit) - **Rationale**: Decompression-bomb protection, bounded parallelism, timeouts, failure behaviour (SECURITY-05, 11, 15). - [ ] Infrastructure Design - CONDITIONAL - **Rationale**: Only if storage is a shared directory (A2); with storage in the database it is skipped. Decided in Application Design. - [ ] Code Generation - EXECUTE (ALWAYS), per unit, build and tests after every unit - [ ] Build and Test - EXECUTE (ALWAYS) - **Rationale**: Full suite, OpenAPI snapshot, golden files with ASF, smoke test extended, LCP measured on both test hosts. ### 🟡 OPERATIONS PHASE - SKIP (decided at Requirements Analysis, Q19 = B). The hero points go into `docs/release-checklist-productie.md`. ## Proposed Units (to be confirmed in Units Generation) | Unit | Content | Depends on | |---|---|---| | H0 | CI: `release/*` condition on `publish-sls-production` and `deploy-sls-production`, docs | none (can be merged early) | | H1 | Image pipeline: validation by content, metadata stripping, resize/compress, variants, focus/crop arithmetic (pure, property-tested) | library decision | | H2 | Hero module backend: entities, migration, admin CRUD, public `GET /hero`, validation, schedule, texts, OpenAPI | H1 for upload | | H3 | Media storage and serving (hash addresses, immutable cache, nosniff, rate limits) | H1 | | H4 | Host injection (region marker, head preload, `hero` key in `#cms-data`, cache invalidation, golden files with ASF) | H2, H3 | | H5 | Admin frontend: hero form, slide list, upload with focus/crop and preview | H2, H3 | | H6 | Seed script (test), docs, release checklist, smoke test extension | H2 to H5 | ## Package Change Sequence 1. H0 (independent; can go to master first). 2. H1, then H2 and H3 (parallel after H1). 3. H4 and H5 (parallel after H2 and H3). 4. H6, then Build and Test on the test hosts with the websites' markers. ## Estimated Timeline - **Total Stages**: 11 to execute (Application Design, Units Generation, Functional Design, NFR Requirements, NFR Design, Infrastructure Design if needed, Code Generation per unit, Build and Test), 3 skipped or not applicable. - **Estimated Duration**: roughly 6 to 9 working days of build time across the units, excluding the websites' own work and Bryan's review time. ## Success Criteria - **Primary Goal**: The hero of both sites comes from the CMS, is live within about a minute, and the LCP element is in the first HTML without a regression. - **Key Deliverables**: `SlpModularCms.Modules.Hero`, media serving, host injection with golden files, admin Hero screen, seed script, `release/*` condition, docs and checklist update. - **Quality Gates**: Security rules compliant (blocking); property tests for the pure functions; full suite green; OpenAPI snapshot updated; smoke tests on both test hosts; LCP measured; no merge or production deploy without Bryan's go. - **Integration Testing**: Both websites with the markers on the test hosts. - **Operational Readiness**: Covered by the joint production checklist (no Operations phase).