Hero-module: execution plan (Workflow Planning)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,168 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user