Files

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).