# Component dependencies: hero-module ## Dependency matrix Rows depend on columns (X = direct use). | | Core.Media | Core.Hosting.Website | Core.Texts | Modules.Hero | Modules.Offerings | Frontend admin | |---|---|---|---|---|---|---| | **Modules.Hero** | X (store, processor, guard, paths, math) | X (`IHtmlPageTransform`, `IIndexHtmlMarkerProvider`, `ICmsDataBlockContributor`, `IIndexHtmlCache`) | X | n/a | none | none | | **Modules.Offerings** | none | X (adds `OfferingsDataContributor`; loses the data block write) | X | none | n/a | none | | **Core.Media** | n/a | none (endpoint is mapped by the host) | none | none (knows no module) | none | none | | **Core.Hosting.Website** | none | n/a | none | none | none | none | | **Frontend admin** | none | none | none | HTTP only (OpenAPI) | HTTP only | n/a | | **Api / site projects** | X (host registers the media endpoint and options) | X | X | X (project reference) | X | n/a | Rules: Core never references a module; the Hero module never references the Offerings module (the data block is composed through the Core contributor interface, so no module knows another). ## Data flow ```mermaid flowchart TD Admin["Admin browser
(HeroPage, FocusEditor)"] -->|"multipart upload, JSON"| HeroCtl["Hero controllers"] HeroCtl --> HeroSvc["HeroService / HeroImageService"] HeroSvc --> Guard["MediaUploadGuard"] HeroSvc --> Proc["ImageProcessor (library)"] HeroSvc --> Store["MediaStore (directory)"] HeroSvc --> Db[("Hero tables
MariaDB")] HeroSvc --> Cache["IIndexHtmlCache"] Db --> PubSvc["PublicHeroService"] PubSvc --> PubApi["GET /api/v1/hero"] PubSvc --> Tr["Hero transform, preload, data contributor"] Tr --> Inj["HtmlMarkerInjector"] Inj --> Page["Website page
(first HTML)"] Store --> MediaEp["GET /media/..."] Page -->|"img, picture, preload"| MediaEp Site["Website (SLS, ASF)"] -->|"refresh after load"| PubApi Page --> Site classDef user fill:#f6e05e,stroke:#c05621,color:#000; classDef host fill:#63b3ed,stroke:#2b6cb0,color:#000; classDef data fill:#9ae6b4,stroke:#2f855a,color:#000; classDef ext fill:#CE93D8,stroke:#6A1B9A,color:#000; class Admin user; class HeroCtl,HeroSvc,Guard,Proc,PubSvc,PubApi,Tr,Inj,MediaEp,Cache host; class Store,Db data; class Page,Site ext; ``` Text alternative: the admin uploads through the Hero services into the media directory and the database; the public read model feeds the public endpoint and the page injection; the browser loads images from the media endpoint and the site refreshes from the public endpoint. ## Communication patterns | From to | Pattern | |---|---| | Admin to host | REST over HTTPS, cookie/JWT as the other admin screens; multipart for the image | | Host internal | Dependency injection; services scoped, `IMediaStore` and `IImageProcessor` singletons (stateless, thread-safe) | | Page build | The injector (singleton with scoped providers) asks transforms in registration order; the data block contributor order fixes the key order | | Site to host | Anonymous GET of `/api/v1/hero` and `/media/...`; ETag and 304 for pages and media | | Change notification | Direct call `IIndexHtmlCache.Invalidate()` after commit | ## Risks and consequences of the design choices | # | Risk or consequence | Mitigation | |---|---|---| | R1 | **Storage in a directory** (Bryan's choice): the directory must survive a deploy, be in the backup and be writable. Pi: place it in the `shared` directory next to `releases/current` and set `Media__Directory`; IIS (MijnHostingPartner, ASF production): write permission is unknown | The store sits behind `IMediaStore`, so a database store can be added without touching the Hero module. Bryan tests directory write access with ASF; if it fails Bryan is asked again. Startup check: the host logs an error and the hero admin upload is refused (public reads unaffected) when the directory is not writable. Backup: add the directory to the host's back-up script and to the release checklist | | R2 | Image library: AVIF encoder and native binaries on win-x64 and linux-arm64, licence | Proof in NFR Requirements; processing behind `IImageProcessor`; WebP is the required output, AVIF optional | | R3 | Wide input list (gif, bmp, tiff, heic/avif) enlarges the attack surface and the library requirements | Allow-list by real signature; decode only through the library inside the guard (pixel, memory and time limits); formats the platform cannot decode are reported as unsupported in the admin; animated input is reduced to the first frame | | R4 | Two writers of `#cms-data` would conflict | Solved by the Core contributor; the Offerings output stays byte-identical (golden files prove it) | | R5 | Variant addresses change when the focus changes; an old page cached by a site may point to removed files | Old set kept for a grace period after a change; sites refresh from the API after load | | R6 | LCP regression if preload and `` differ | One renderer for both, golden-tested with the ASF files | | R7 | Two preload links (portrait, landscape) double the first request when a browser ignores `media` on preload | Verified in the LCP measurement on both test hosts |