Files

5.1 KiB

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, 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

flowchart TD
    Admin["Admin browser<br/>(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<br/>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<br/>(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 <picture> 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