# Requirements: Media library (media-library) - **Feature slug**: media-library - **Status**: Draft on assumptions (Bryan is away; he checks `assumptions-and-open-questions.md` later and corrects where needed) - **Depth**: Standard (comprehensive for deletion, file serving and the data migration, which are security and data-loss relevant) - **Documentation Language**: English; **Conversation Language**: Dutch - **Inputs**: `overview.md` (Bryan's requirements 1 to 7, 2026-11-17), the Hero module as built (`Core/Media`, `Modules.Hero`), `docs/hero-module.md`, the gallery needs of ASF (shoot-page mosaic, masonry) as relayed by SLS-Main. ## 1. Intent analysis | Item | Value | |---|---| | User request | One place in the CMS where photos are managed, kept and reused by all modules; nothing is removed automatically; a clean-up tool and bulk actions in the admin | | Request type | New capability (Core abstraction plus a new admin area), later used by a gallery module | | Scope | Core (media model and usage register), `Modules.Hero` (becomes a first user), new admin screen, later a gallery module | | Complexity | Complex: abstraction at the right level, address stability, data migration of existing `HeroImages` | | Reverse engineering | Targeted read only: `Core/Media` (store, paths, variants, focus), `Modules.Hero` (entity `HeroImage`, `HeroMediaCleanup`, render service) | ## 2. What exists today (facts the design builds on) - `IMediaStore` stores originals and variant sets on disk (`Media__Directory`); public address `/media/{area}/{setHash}/{ratio}-{width}.{ext}` (`MediaPaths`, strict allow-list). `area` is a module name (`hero`). - The **set hash** is 16 hex characters of SHA-256 over the original's hash and the crops (ratio name plus canonical focus), so a changed focus gives a new address and files are cached for a long time. - `HeroImage` holds the original (hash, key, size), one general focus and an optional focus per ratio (`wide`, `tall`), the current set hash and its variants. A slide references an image. Uploading the same photo twice gives one image (same hash). - A background renderer (`HeroRenderService`) cuts variants; an image without a complete set is not published. - `HeroMediaCleanup` retires uploaded-but-unused images after `Media:RetentionDays` (7) and removes retired files after the same period. This is the automatic clean-up Bryan wants to stop. ## 3. Principles (from Bryan, 2026-11-17) 1. **Keep everything.** An upload stays until a person deletes it. 2. **A person decides what goes**: through "Clean up" (a guided, previewed bulk delete) or through bulk actions in the library. 3. **Crop per use, not per photo.** A photo has a default focus; every use (module and place) can carry its own crop. A photo in a masonry gallery needs no crop. 4. **Addresses stay stable.** `/media/hero//...` and the set hashes do not change; ASF, SLS and the golden files keep working. ## 4. Functional requirements | ID | Requirement | Acceptance criteria | |---|---|---| | ML-01 | **Library overview.** An admin screen lists all photos of all modules, newest first, with a thumbnail, file name, size, upload date and a usage indicator. | Order is `CreatedAt` descending; paging or incremental loading beyond 100 photos; an empty state; keyboard and screen-reader usable. | | ML-02 | **Usage indicator.** Per photo: "in use" or "not used", and where (module and place, for example "Hero, slide 3"). | Several uses are all listed; the indicator is computed from the modules' own data, not guessed; a photo used nowhere shows "Not used". | | ML-03 | **Keep everything.** No automatic removal of any photo or its files. | The Hero step that retires unattached images is switched off once the library owns the retention (see section 8, phase A: behind a setting, default decided in the assumptions); a test proves nothing is removed without a person's action. | | ML-04 | **Selection component** (own reusable component): checkboxes per photo, select all and clear, a range with shift-click, keyboard operation, a visible count, and a live-region announcement of the count. | Works for mouse, keyboard and screen reader; reused by the library and the clean-up; uses the shared `Checkbox` of the theme. | | ML-05 | **Bulk actions** on the selection, in the library itself. First action: **Delete**. The action bar is a separate component so more actions (tags, move) can be added without touching the list. | Delete asks for confirmation naming the number of photos and how many are in use; a failure of one photo does not stop the others and is reported per photo. | | ML-06 | **Delete rules.** A photo that is in use is not deleted unless the person explicitly confirms and the use is detached first. | Default: in-use photos are not selectable for delete in "Clean up" and are marked in the library; deleting an in-use photo from the library shows what will lose its image and requires a second confirmation; the host falls back as it does today for a slide without a set. | | ML-07 | **"Clean up" button.** Opens the overview of photos that would be cleaned: default everything older than 7 days, with a slider to look more or fewer days back, and a checkbox **Only unused photos**, default on (off = all photos in the period). | The list is newest first; all rows start selected; the person can deselect before confirming; confirming deletes exactly the selected rows; the summary shows the number and the bytes that will be freed. | | ML-08 | **Clean-up is the same component as the library** (ML-04, ML-05) in a preselected view, not a second implementation. | One list/selection component, two entry points. | | ML-09 | **Storage usage and limit warning.** The screen shows the used space (originals plus variants), the configured limit, and a warning at a threshold and at the limit. | Used bytes are computed from the store and cached for a short time; the warning level is configurable (assumption: 80 percent); at the limit, uploads give a clear message instead of a failure; the existing `Media:MaxTotalBytes` (2 GB) is the limit. | | ML-10 | **Upload into the library** (single and multiple), with the same limits and checks as Hero today (type signature, size, megapixels, rate limit). | The Hero upload path and the library share one upload service; the same file is one photo (hash). | | ML-11 | **Crop per use.** A use (module, place, ratio) can have its own focus and zoom, defaulting to the photo's default focus. Changing a use's crop never affects other uses. | A use owns its crop; the set hash of a use is derived exactly as today from the original's hash plus that use's crops, so addresses stay as they are. | | ML-12 | **Default focus per photo.** The photo carries the default focus that new uses start from. | Setting it does not change existing uses that have their own crop. | | ML-13 | **Usage register for modules.** A module reports where it uses photos and can be asked to detach a photo. | Contract in the design (section 3 of the application design); Hero is the first provider; a module without a provider counts as "uses nothing" and the library shows a warning that its uses are unknown (so a photo is not silently deleted). | | ML-14 | **Public addresses unchanged.** `/media/hero//-.` and every existing set hash stay valid. | Golden files and the host-injection tests stay green without edits; a regression test serves a set created before the library. | | ML-15 | **Permissions.** Owner and Administrator may use the library (like Hero and Offerings). | `[Authorize(Policy = "AdminOnly")]`; rate limits on upload and bulk delete. | | ML-16 | **Audit.** Each deletion (single, bulk, clean-up) is logged with user, photo ids and count. | Structured log entry per action; no photo content in the log. | ## 5. Non-functional requirements | ID | Requirement | |---|---| | NFR-ML-01 | **Data safety**: a delete is a two-step action (confirm, then act) and the originals can be kept behind a short "trash" delay (assumption 12). No data-moving migration runs without a recent back-up and prior alignment. | | NFR-ML-02 | **Security** (Security Baseline): the same upload checks as Hero (content signature, size, pixel limit, rate limit), strict address allow-list, no path from user input, authorisation on every endpoint, bulk delete limited in size per request. | | NFR-ML-03 | **Performance**: the overview loads the first page within 500 ms on the Raspberry Pi test host (thumbnails come from existing variants, never decoding originals in the request); storage usage is cached. | | NFR-ML-04 | **Accessibility**: WCAG 2.2 AA; selection, range and bulk actions work by keyboard; counts are announced; no information by colour alone; forced-colors safe (shared Checkbox). | | NFR-ML-05 | **Compatibility**: no change to the public address scheme, set-hash algorithm, `HeroImages` table or golden files in phase A. | | NFR-ML-06 | **Testability**: selection state, clean-up selection (age and unused filter) and the set-hash derivation per use are pure functions with unit and property tests. | | NFR-ML-07 | **Operability**: storage limit and warning level configurable (`Media__*`), documented in the release checklist when built. | ## 6. Design sources - **Hero**: general focus plus `wide` and `tall` crops, background rendering, usage by slides, retention logic. It shows what a "use" is today (a slide with a ratio set) and what must keep working. - **ASF gallery needs**: the shoot-page **mosaic** has several tile ratios per page (so crop per use and several ratios per photo), the **masonry** gallery shows a photo in its own ratio (no crop, only a variant set in the natural ratio). Both are served by "a use decides its ratio set", with a natural-ratio use as a first-class case. - **Thumbnails** in the library are a use of the library itself (ratio `thumb`), cut once per photo. ## 7. Out of scope (for now) - Tags, albums, search by content, moving photos between modules (the bulk action bar leaves room). - Replacing a photo's file while keeping its uses (replace-in-place). - Video or other media types. - A CDN or database-backed store (`IMediaStore` already allows it; see Hero assumption 20). ## 8. Constraints and the migration question - The existing `HeroImages` table and the Hero admin keep working unchanged in phase A. The library **reads through** the Hero data (a provider that lists `HeroImages` as photos and slides as uses) before any data moves. - Moving existing photos into a Core table (phases B and C below) is a data migration that needs a back-up and prior alignment; it is designed here and **not built**. - The automatic retirement of unattached Hero images (7 days) stays until the library can show and delete photos (phase A done); then it is switched off by setting, default per assumption 3. ## 9. Workflow plan (phases) | Phase | Content | Moves data? | Build now? | |---|---|---|---| | A. Foundations (safe, reversible) | Usage contract in Core (`IMediaUsageProvider`), Hero provider (read only), library read model over `HeroImages`, storage usage service, selection and bulk-action components (frontend), clean-up selection logic, library screen (list, usage, selection, bulk delete through the Hero service), Hero retention setting | No (delete uses existing Hero delete path) | After Bryan acknowledges the assumptions; pure and read-only parts can start earlier | | B. Own tables | `MediaAsset` and `MediaUse` tables, upload into the library, default focus | New tables only | Needs alignment | | C. Migration of Hero | Copy `HeroImages` into `MediaAsset` plus `MediaUse` (one use per slide), keep set hashes and addresses, switch Hero to the library, drop old columns later (expand then contract) | Yes | Needs alignment and a back-up | | D. Gallery module | First other consumer (mosaic, masonry) | Own data | Separate feature | ## 10. Traceability to Bryan's requirements | Bryan (overview.md) | Here | |---|---| | 1 Keep everything | ML-03, principle 1 | | 2 Clean-up button, slider, only unused | ML-07 | | 3 Overview newest first, usage indicator | ML-01, ML-02, ML-07 | | 4 and 6 Bulk actions as own component | ML-04, ML-05, ML-08 | | 5 Storage and limit warning | ML-09 | | 7 Crop per use | ML-11, ML-12, design section 4 | | Boundary: addresses and set hashes | ML-14, NFR-ML-05 |