Files
2026-11-16 14:21:44 +01:00

10 KiB

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

flowchart LR
    Admin["Admin frontend<br/>(Hero screen)"]
    Hero["Modules.Hero<br/>(new)"]
    Core["Core<br/>(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

flowchart TD
    Start(["User Request"])

    subgraph INCEPTION["🔵 INCEPTION PHASE"]
        WD["Workspace Detection<br/><b>COMPLETED</b>"]
        RE["Reverse Engineering<br/><b>SKIP</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</b>"]
        NFRA["NFR Requirements<br/><b>EXECUTE</b>"]
        NFRD["NFR Design<br/><b>EXECUTE</b>"]
        ID["Infrastructure Design<br/><b>CONDITIONAL</b>"]
        CG["Code Generation<br/>(Planning + Generation)<br/><b>EXECUTE</b>"]
        BT["Build and Test<br/><b>EXECUTE</b>"]
    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

  • Workspace Detection (COMPLETED)
  • Reverse Engineering (SKIPPED: targeted review; _shared/ artifacts exist)
  • Requirements Analysis (COMPLETED, approved by Bryan 2026-11-16)
  • 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.
  • 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).