# Application Design: hero-module (consolidated) Details: [components.md](components.md), [component-methods.md](component-methods.md), [services.md](services.md), [component-dependency.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 `ICmsDataBlockContributor`s; 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 `…` (first slide as ``) and `…` in the head (one or two preload links with `media`, byte-equal to the ``/`` attributes); only WebP in the LCP picture and the preload; addresses `/media/hero//-.`, 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 ```mermaid flowchart LR Admin["Admin (Hero screen)"] --> Hero["Modules.Hero"] Hero --> Media["Core.Media
(store, processor, guard, endpoint)"] Hero --> Inj["Core.Hosting.Website
(transforms, data block, cache)"] Off["Modules.Offerings"] --> Inj Inj --> Pages["Website pages (SLS, ASF)"] Media --> Pages Dir[("Media directory
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 `` 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).