5.1 KiB
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 |