5.0 KiB
Application Design: hero-module (consolidated)
Details: components.md, component-methods.md, services.md, component-dependency.md. Inputs: requirements.md, site-contract-agreed-with-asf.md, answers to application-design-plan.md (2026-11-16).
Decisions
| # | Decision | Source |
|---|---|---|
| D1 | One module SlpModularCms.Modules.Hero (own DbContext, migrations, texts); on or off per site |
Q14 (requirements) |
| D2 | A general media service in Core.Media: storage interface, image processor interface, upload guard, pure FocusMath and VariantPlanner, address scheme, media endpoint. Usable later for a gallery |
Design Q4 = B |
| D3 | Images are stored in a directory outside the release behind IMediaStore; a database store can follow if the hosting requires it. Risk R1 recorded; Bryan tests write access on the ASF hosting and is asked again if it fails |
Design Q1 = B |
| D4 | Input formats: as many as the library can decode (jpg/jpeg, png, webp always; gif, bmp, tiff, heic/avif where possible), real-signature check, metadata stripped, animation reduced to the first frame; output chosen by the system per platform (WebP required, AVIF when possible) | Design Q2 |
| D5 | #cms-data is composed by a Core CmsDataBlockTransform from ICmsDataBlockContributors; Offerings becomes a contributor with byte-identical output; the Hero adds hero |
Design Q3 = A |
| D6 | Crop model B: the host cuts wide (3:2) and tall (4:5) variants around the focus point and zoom. The focus defaults to the centre for all ratios; a separate focus (and zoom) per ratio is optional and falls back on the general one |
Design Q6, contract |
| D7 | The admin focus editor is an own light component (draggable point, zoom, live wide and tall previews using a TypeScript twin of FocusMath with shared test vectors) |
Design Q5 = A |
| D8 | Public contract: GET /api/v1/hero (204 = none), the same shape under hero in #cms-data; region pairs <!--CMS:HERO-HTML-->…<!--/CMS:HERO-HTML--> (first slide as <picture>) and <!--CMS:HERO-PRELOAD-->…<!--/CMS:HERO-PRELOAD--> in the head (one or two preload links with media, byte-equal to the <source>/<img> attributes); only WebP in the LCP picture and the preload; addresses /media/hero/<setHash>/<ratio>-<width>.<ext>, immutable |
Contract with ASF |
| D9 | One renderer (HeroPictureRenderer) produces both the region attributes and the preload attributes; one read model (PublicHeroService) feeds the API, the region, the preload and the data block |
LCP requirement |
| D10 | Fail-open for page injection, fail-closed for uploads | Requirements, SECURITY-15 |
| D11 | Language: the hero row carries a Language (default nl, unique), so adding a language needs no migration of existing rows; only one is exposed and edited now |
Q9 |
Architecture overview
flowchart LR
Admin["Admin (Hero screen)"] --> Hero["Modules.Hero"]
Hero --> Media["Core.Media<br/>(store, processor, guard, endpoint)"]
Hero --> Inj["Core.Hosting.Website<br/>(transforms, data block, cache)"]
Off["Modules.Offerings"] --> Inj
Inj --> Pages["Website pages (SLS, ASF)"]
Media --> Pages
Dir[("Media directory<br/>outside the release")] --- Media
Db[("MariaDB")] --- Hero
classDef new fill:#FFA726,stroke:#E65100,color:#000;
classDef chg fill:#BBDEFB,stroke:#1565C0,color:#000;
classDef ext fill:#C8E6C9,stroke:#2E7D32,color:#000;
class Hero,Media new;
class Inj,Off,Admin chg;
class Pages,Dir,Db ext;
Text alternative: the new Hero module and Core.Media (orange) work with the changed injection layer and Offerings (blue); media files live in a directory outside the release and metadata in the database; pages get the hero injected.
Open items carried to the next stages
| Item | Stage |
|---|---|
| Choice and proof of the image library (win-x64, linux-arm64, formats, AVIF, licence), limits (pixels, memory, parallelism, timeouts), budgets for LCP and weight, maximum slides, grace period for old sets | NFR Requirements and NFR Design |
| Whether deleting an image used by a slide refuses or detaches; exact validation messages; byte-exact HTML of the region | Functional Design |
| Write permission of the directory on MijnHostingPartner (IIS) and the backup of the directory | Bryan with ASF; Infrastructure Design (storage is a directory, so this stage now executes for the media unit) |
Golden files for <picture> and the preload; focus estimates for the 8 photos |
ASF session |
| SLS rendering of the three-line title and its screen-reader text | SLS session |
Units (confirmed from the execution plan, adjusted)
H0 (done, PR #16 merged, 0824bfa) · H1 image pipeline (Core.Media processor, guard, FocusMath, VariantPlanner) · H2 Hero module backend · H3 media store, endpoint, address scheme · H4 injection (data block contributor and Offerings change, region, preload, golden files) · H5 admin frontend · H6 seed, docs, smoke test. Infrastructure Design is now needed for H3 (directory storage).