12 KiB
12 KiB
Requirements: Media library (media-library)
- Feature slug: media-library
- Status: Draft on assumptions (Bryan is away; he checks
assumptions-and-open-questions.mdlater 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)
IMediaStorestores originals and variant sets on disk (Media__Directory); public address/media/{area}/{setHash}/{ratio}-{width}.{ext}(MediaPaths, strict allow-list).areais 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.
HeroImageholds 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. HeroMediaCleanupretires uploaded-but-unused images afterMedia: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)
- Keep everything. An upload stays until a person deletes it.
- A person decides what goes: through "Clean up" (a guided, previewed bulk delete) or through bulk actions in the library.
- 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.
- Addresses stay stable.
/media/hero/<hash>/...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/<setHash>/<ratio>-<width>.<ext> 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
wideandtallcrops, 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 (
IMediaStorealready allows it; see Hero assumption 20).
8. Constraints and the migration question
- The existing
HeroImagestable and the Hero admin keep working unchanged in phase A. The library reads through the Hero data (a provider that listsHeroImagesas 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 |