Hero-module: Application Design (componenten, methoden, services, afhankelijkheden); antwoorden van Bryan verwerkt
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,70 @@
|
||||
# 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<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 |
|
||||
Reference in New Issue
Block a user