169 lines
10 KiB
Markdown
169 lines
10 KiB
Markdown
# 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<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
|
|
|
|
```mermaid
|
|
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
|
|
- [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).
|