10 KiB
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,herokey 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
- H0 (independent; can go to master first).
- H1, then H2 and H3 (parallel after H1).
- H4 and H5 (parallel after H2 and H3).
- 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).