Continuous Integration / changes (pull_request) Successful in 14s
Continuous Integration / config-sls (pull_request) Successful in 9s
Continuous Integration / config-asf (pull_request) Successful in 8s
Continuous Integration / backend-test (pull_request) Canceled after 0s
Continuous Integration / frontend-prepare (pull_request) Canceled after 0s
Continuous Integration / frontend-build (pull_request) Canceled after 0s
Continuous Integration / frontend-test (pull_request) Canceled after 0s
Continuous Integration / frontend-lint (pull_request) Canceled after 0s
Continuous Integration / publish-sls-test (pull_request) Canceled after 0s
Continuous Integration / publish-sls-production (pull_request) Canceled after 0s
Continuous Integration / deploy-sls-test (pull_request) Canceled after 0s
Continuous Integration / deploy-sls-production (pull_request) Canceled after 0s
Continuous Integration / publish-asf-test (pull_request) Canceled after 0s
Continuous Integration / deploy-asf-test (pull_request) Canceled after 0s
Continuous Integration / smoke-sls-test (pull_request) Canceled after 0s
Continuous Integration / smoke-asf-test (pull_request) Canceled after 0s
Continuous Integration / backend-build (pull_request) Canceled after 48s
Continuous Integration / compile-sites (pull_request) Canceled after 52s
Continuous Integration / vulnerability-scan (pull_request) Canceled after 57s
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
15 KiB
15 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 (to the trash, ML-18). 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 (decision 10). A photo that is in use can be deleted after a second confirmation that names the places; the module detaches it first (Hero: its slides are removed). | The first confirmation says how many photos and how many are in use; the second names the places per photo; the server refuses a photo in use unless the request carries the confirmation and checks the usage again at that moment; one photo failing does not stop the others and is reported per photo. |
| ML-07 | "Clean up" button. Opens the overview of photos that would be cleaned: default everything not used for more than 7 days (counted from the LAST USE, decision 8), 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-17 | Choose or upload, in every part that needs an image (new requirement of Bryan, 2026-11-17). In every module that needs an image (Hero, later gallery, mosaic, masonry) the person can upload on the spot, also when the library holds no suitable image yet, and can choose from the existing library photos. An image uploaded on the spot is added to the library automatically and can be chosen everywhere afterwards. | One shared component "choose or upload" (a picker of the library photos plus an upload button) is reused by every module; it applies the same validation, limits and background processing as the Hero upload today; after an upload the new photo is chosen at once; the module keeps its own use (place, crop) of the chosen photo; a photo uploaded in one module is listed and choosable in the others. Until the library owns uploads (phase B) the Hero upload flow stays as it is. |
| 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) | The shared ImagePicker component (pure, not wired), 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 (one library record per upload, ML-17), 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 |
| 8 (2026-11-17) Choose or upload in every part that needs an image | ML-17, design section 10 |
| 7 Crop per use | ML-11, ML-12, design section 4 |
| Boundary: addresses and set hashes | ML-14, NFR-ML-05 |
11. Added by decisions of 2026-11-17
| ID | Requirement | Acceptance criteria |
|---|---|---|
| ML-18 | Trash (decision 12). Delete means "to the trash": recoverable for 7 days (Media:TrashDays); a trash view lists the photos with Restore; after the period the files are removed by the existing retired-file mechanism. Uploading the same file again brings it back. |
A trashed photo is hidden from the hero and from the renderer; restore returns it (without its old slides); the clean-up of the trash is idempotent; a photo is never removed while it is referenced. |
| ML-19 | Original file name is stored at every upload (additive) and shown in the library; photos from before keep a neutral label. | The name is cleaned (no path, no control characters, at most 200 characters) and never used as a path. |
| ML-20 | Last use per photo: the moment it was last detached from a slide (or trashed); the clean-up period counts from there, from the upload date for a photo that was never used. | See assumption 29. |
| ML-21 | Migration of the Hero photos to the library's own tables, expand then contract, same ids, hashes and addresses; documented back-up and rollback first; test only; SLS-Main is told before a test deploy. | See migration-plan.md. |