Files

56 lines
5.0 KiB
Markdown

# 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 `<!--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
```mermaid
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).