# Functional Design: business logic model (units H1 to H5) Bundled for all units; answers of Bryan (2026-11-16) are applied. Names refer to `application-design/`. HTML for the region and preload is defined by the ASF golden files (`web/contract/host-injection/hero/`, commit 13f78c4), which are authoritative. ## H1. Image pipeline ### Upload admission (`IMediaUploadGuard.AdmitAsync`) 1. Reject at once when the declared length is above the maximum (10 MB) or the stream turns out longer (read through a counting stream, stop at the limit). 2. Read the first bytes and decide the format from the **signature**, never from a name or `Content-Type`: JPEG, PNG, GIF, BMP, TIFF (both byte orders), WebP (`RIFF....WEBP`), and the ISO-BMFF family for AVIF and HEIC/HEIF (`ftyp` with brand `avif`, `avis`, `heic`, `heix`, `hevc`, `mif1`, `msf1`). Anything else (SVG, PDF, executables, text) is rejected as `unsupported_format`. 3. Inspect through the library with an explicit format and resource limits: pixel size, frame count. Reject `too_many_pixels` (above the pixel ceiling), `corrupt` (decode error), `timeout`. 4. Animated input (GIF, WebP, AVIF sequences) is reduced to the first frame. 5. Wait for a free processing slot (at most `MaxParallelJobs`); when none frees within a few seconds answer `busy` (HTTP 429). ### Render planning (pure) For an image of `W x H` pixels, a ratio `r = n:d`, a focus setting `(fx, fy, z)` (centre `0.5, 0.5` and `z = 1` by default; a ratio may have its own setting, otherwise the general one applies): - The **largest crop** of ratio `r` inside the image: `cw0 x ch0` (if `W/H > n/d` then `ch0 = H`, `cw0 = ch0 * n / d`, else `cw0 = W`, `ch0 = cw0 * d / n`). - With zoom `z >= 1` the crop is `cw = cw0 / z` by `ch = ch0 / z`. - The crop is centred on the point `(fx * W, fy * H)` and then moved the smallest amount needed to lie inside the image. So the subject stays as close to the centre of the crop as the image allows, and a crop never leaves the image. - Widths: from the configured steps for the ratio (`wide`: 640, 960, 1280, 1600, 2560; `tall`: 480, 640, 960, 1280) keep those `<= cw` (never upscale). If none is `<= cw`, one variant at `cw` is made. The height is `round(width * d / n)`. - Formats per width: WebP always; AVIF when the processor reports AVIF output; the page-critical HTML uses WebP only (contract). - Quality: WebP 80, AVIF 50. Metadata is removed from every output; EXIF orientation is applied before cropping. ### Set hash and addresses `setHash` = first 16 hex characters of SHA-256 over the canonical string `sha256-of-original | wide:fx,fy,z | tall:fx,fy,z` (numbers rounded to 4 decimals, invariant culture). A change of focus therefore gives a new set and new addresses; an identical upload of the same photo with the same focus gives the same set (no second copy is stored). Variant file name: `-.` (`wide-1600.webp`, `tall-960.avif`); address `/media/hero//`. ### Self-test at start-up The processor decodes and encodes a tiny embedded image in every supported format and logs the capability list (input and output formats, library version). A failure marks the processor unavailable: uploads answer 503 with a generic message; reading and publishing are unaffected. ## H3. Media store and serving - **Keys**: variants `hero//-.`; originals `originals/.` (never served). Only keys made by the code exist; a client file name is never used in a path. - **Write**: a set is written to a temporary directory next to the target and moved into place with one rename; a half-written set is never visible. - **Serve** `GET|HEAD /media/{**path}`: the path must match `^hero/[0-9a-f]{16}/(wide|tall)-[0-9]{2,5}\.(webp|avif|jpg)$` (area pattern from a registered allow-list, so other areas can register their own); otherwise 404. Headers: `Content-Type` from the extension, `Cache-Control: public, max-age=31536000, immutable`, strong `ETag` (from the set hash and name), `X-Content-Type-Options: nosniff`, `Vary: Accept-Encoding` not needed (images are not recompressed). `If-None-Match` equal gives 304. Rate limit policy `media-public`. - **Clean-up** (hosted service, daily): removes sets and originals that no image row references and that are older than 7 days (a retired set is stamped when it stops being referenced; the files go 7 days later). Never removes a referenced file. - **Free space and size**: before writing, check free space (at least the expected output plus a margin) and the total size of the media directory against the safety limit `Media:MaxTotalBytes`; refuse with a generic message when exceeded. ## H2. Hero backend ### Save (`PUT /api/v1/hero`, whole hero replaced) Input: hero fields, buttons, display, schedule, slide list in order (`id` optional for a new slide, `imageId`, `alt`, `decorative`, `isActive`). In one transaction: validate everything, update the hero, upsert slides, remove slides no longer listed, renumber the order, record actor and time. Afterwards `IIndexHtmlCache.Invalidate()`. ### Public read model (`PublicHeroService.GetActiveAsync`) Returns null (204) when: no hero row for the language, `IsActive` false, `now` before `StartsAt` or at or after `EndsAt`, or the hero has no title. Otherwise: only active slides that have a stored image; a slide without alt that is not decorative is **not** published (the admin does not allow saving it anyway); order as saved. Each slide carries the general focus, plus the per-ratio overrides, and all stored variants (WebP and AVIF) with their ratio, width, type and address. The result is also what the HTML transform and the data block use, so the three always agree. ### Image operations - **Upload** (`POST /api/v1/hero/images`): guard, store original, render the planned sets for the default focus, save the row, return the image with its variants. - **Set focus** (`PUT /api/v1/hero/images/{id}/focus`): validate ranges (`0..1`, zoom `1..4`), compute the new set hash, render the sets into new addresses, update the row, stamp the old set as retired; the slides keep pointing at the same image id. - **Delete** (`DELETE /api/v1/hero/images/{id}`): refused with 409 and a clear message while any slide uses the image (Bryan, Q1); otherwise the row goes and its set and original are stamped retired. ## H4. Injection Order of work for a page that mentions hero markers: get `PublicHeroDto?` once per request cycle; if null, leave regions and preload as baked (and the data block carries `"hero": null`); otherwise: 1. `HERO-HTML` region: exactly the ASF golden rules (title lines with `
`, tagline span, buttons, first kept slide as ``; slides skipped when they have no alt and are not decorative, a path outside our host, or no size; WebP only; `object-position` from the focus of the ratio that the `img` shows, i.e. the general focus). 2. `HERO-PRELOAD` region in the head: one preload for `tall` with `media="(orientation: portrait)"` and one for `wide` with `media="(orientation: landscape)"` when both exist; one without `media` when only one ratio exists; `srcset`, `sizes`, `media` byte-equal to the picture. 3. Data block: key `hero` with the whole `PublicHeroDto` (all slides) in the shared block. Fail-open: any exception, an unreadable hero or a missing marker leaves that part as baked; a failing data-block contributor leaves the whole block as baked. **Safety ceiling for unlimited slides** (Bryan: no administrator limit, a technical ceiling only): the hero endpoint, the HTML transform and the data block never emit more than `Hero:MaxPublishedSlides` slides (default 50, configurable) so the first HTML and the data block cannot grow without bound; when a hero has more active slides the first 50 in order are published and the admin shows a notice. The ceiling is reported to Bryan; LCP and page weight stay leading (the first HTML contains only the first slide). ## H5. Admin Screens and states are in `frontend-components.md`; the admin only shows a **live badge** (Bryan, Q5): "Live" or "Niet live" with the schedule dates, no long reason text. Uploads are limited per user (20 per hour). Every validation message comes from the server (`ProblemDetails`-style error with a field) and is shown at the field.