Files
slp-modular-cms/aidlc-docs/features/media-library/inception/requirements/requirements.md
T
SluijsensandClaude Sonnet 5.5 a01bcd33c4
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
Mediabibliotheek: verwijderen naar prullenbak in de UI, terugzetten, opruimen bevestigen, migratieplan, besluiten van Bryan in de docs
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-17 15:18:15 +01:00

15 KiB

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/<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 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) 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.