Files
slp-modular-cms/aidlc-docs/features/media-library/assumptions-and-open-questions.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

20 KiB

Assumptions and deferred questions: media-library

Kept while Bryan is away (2026-11-17): no questions to him, a most probable assumption per open question instead. Per item: the question, the assumption made, what changes if Bryan chooses differently, and where in code or design. To be put to Bryan by the SLS session; he checks and corrects later. Same form as the Hero list.

# Question Assumption made If Bryan chooses differently Where
1 Which uses (places and ratios) exist? [Confirmed by Bryan "as designed", 2026-11-17] Hero wide (3:2) and tall (2:3), ASF shoot-page mosaic tiles (a small fixed set of ratios per page, to be listed by the ASF session), masonry (natural ratio, no crop), thumb (library thumbnails, 1:1 or natural). A use is (module, place, ratio set). Other ratios only add rows to the use definitions; a free-form ratio per tile would need a ratio editor and more variants per photo. Application design section 4 (MediaUseDefinition)
2 Several formats/variants per photo: who decides the set? [Confirmed by Bryan "as designed", 2026-11-17] The use decides the ratios and widths (as VariantPlanner does for Hero); the library never cuts a fixed set per photo. Formats stay WebP and AVIF as today. A fixed set per photo costs more disk and CPU on the Pi and cuts variants nobody uses. VariantPlanner, application design section 4
3 The 7-day automatic clean-up of unattached Hero images until the library is built. [Decided by Bryan, 2026-11-17, second round: see "Decisions of the second round"] Built (2026-11-17, safe: default unchanged): the setting Media:AutoCleanupUnattached exists, default true (today's behaviour); set Media__AutoCleanupUnattached=false per host to keep every upload. Plan: switch it off (default false) once the library screen and delete are accepted by Bryan. Switch it off behind a setting (Media:AutoCleanupUnattached, default true until the library screen exists, then default false), so nothing is lost silently once the library can show and delete photos. Retired-file removal (after a replaced set) stays: that is housekeeping of generated files, not a person's photos. Keep it on until phase C; or switch off now (risk: unused uploads pile up with no screen to remove them). HeroMediaCleanup, MediaOptions
4 Rights per module: who may see, use and delete which photos? [Decided by Bryan, 2026-11-17, second round: see "Decisions of the second round"] One shared library for Owner and Administrator (like Hero and Offerings). No per-module visibility yet. Per-module visibility needs an owner field on a photo and a filter; the contract has room for it (ModuleKey on a use). [Authorize(Policy = "AdminOnly")], MediaUse.Module
5 Public addresses: per module (/media/<module>/...) or a shared path? [Confirmed by Bryan "as designed", 2026-11-17] Keep /media/{area}/{setHash}/{name}; area stays the module (hero; a gallery would use gallery). The set hash still comes from the original's hash plus the crops of that use. A photo used in two modules is two sets (two addresses), cached separately. A shared path would change addresses and golden files: not allowed without alignment. MediaPaths, MediaEndpoint
6 Usage register: do modules report, or does the library keep it centrally? [Confirmed by Bryan "as designed", 2026-11-17] Modules report: IMediaUsageProvider per module answers "where is this photo used" and "detach this photo" from the module's own data. Computed, never copied, so it cannot go stale. The library warns when a module has no provider. A central register table keeps the answer fast but must be kept in step on every module save (risk of drift); can be added later as a cache. Application design section 3, IMediaUsageProvider
7 What counts as "unused" in the clean-up? [Decided by Bryan, 2026-11-17, second round: see "Decisions of the second round"] A photo is unused when no provider reports a use. A photo used only by an inactive or unpublished slide still counts as used (it is in a slide). Treating an inactive slide as unused would delete photos a person may want to switch on again; stricter would be safer than looser. MediaUsageService
8 Clean-up default period and slider range. [Decided by Bryan, 2026-11-17, second round: see "Decisions of the second round"] Default 7 days, slider 1 to 365 days, step 1; "Only unused photos" on. The period is measured from the upload date. Measured from last use, or another range: a one-line change in the filter. Clean-up component, CleanupSelection
9 Storage limit and warning. [Confirmed by Bryan "as designed", 2026-11-17] Limit = existing Media:MaxTotalBytes (2 GB, decided by Bryan, Hero assumption 12). Warning at 80 percent (amber) and at 100 percent (red, uploads refused with a clear message). Used bytes = originals plus all variants, cached 60 s. Another threshold or limit: configuration only. MediaOptions, MediaStorageUsage
10 Delete of a photo that is in use. [Decided by Bryan, 2026-11-17, second round: see "Decisions of the second round"] Not possible from Clean-up (those rows are not selectable); possible from the library after a second confirmation that names the uses; the module detaches it first (Hero: the slide loses its image and is unpublished until a new one is chosen, as today). Block deleting in-use photos completely: the extra confirmation path is removed. IMediaUsageProvider.DetachAsync, library screen
11 Shared upload service: does Hero's upload move into the library? [Confirmed by Bryan "as designed", 2026-11-17] In phase A Hero keeps its own upload endpoint; the library also lists those photos. In phase B both call one upload service in Core. Moving Hero upload earlier gives a single path sooner but touches Hero before the data model exists. HeroImageService, MediaUploadGuard
12 Trash delay (deleted photos recoverable for a while)? [Decided by Bryan, 2026-11-17, second round: see "Decisions of the second round"] No trash in phase A: the confirmation naming the count is the safety. A 7-day trash can be added in phase B (a DeletedAt and the existing retired-file mechanism). Trash from the start: reuse HeroRetiredFile logic generalised in Core; about 1 day extra. HeroRetiredFile, application design section 5
13 Migration of existing HeroImages (phase C). [Decided by Bryan, 2026-11-17, second round: see "Decisions of the second round"] Expand then contract: new MediaAsset and MediaUse tables are filled from HeroImages and HeroSlides with the same ids, hashes and set hashes; Hero reads the library; old columns are dropped in a later release. Needs a back-up and alignment: not built. A one-step move is smaller but cannot be rolled back; or no migration at all and the library keeps reading through Hero (the provider approach) until the gallery module needs own tables. Requirements section 9, application design section 6
14 Crop per use: data per use or per photo? [Confirmed by Bryan "as designed", 2026-11-17] A use owns its crop (focus x, y and zoom per ratio); the photo owns the default focus new uses start from. The set hash of a use is SetHash(originalSha256, crops of that use) exactly as today, so existing Hero addresses are unchanged. Crop per photo only (today's model) cannot serve a mosaic with several tiles of the same photo. MediaPaths.SetHash, MediaUse
15 Selection range with shift-click and "select all": across pages or the loaded page? [Confirmed by Bryan "as designed", 2026-11-17] The loaded list (the clean-up list is loaded fully, the library list incrementally; "select all" says how many are loaded and offers "select all N" for a filtered list). Strictly the current page: simpler, less useful for a clean-up of hundreds. Selection component
16 Deleting files from the store when a photo is deleted. [Confirmed by Bryan "as designed", 2026-11-17] The original and the set directories of that photo are deleted through IMediaStore after the database rows; a set shared with another use (same hash) is kept until no use references it. Soft delete first (see 12). IMediaStore.DeleteSetAsync, HeroRepository.GetReferencedSetHashesAsync
17 Language of the screen: nl and en like the rest of the admin. Yes, media.* keys in both files; terms: "Mediabibliotheek", "Opruimen", "Alleen ongebruikte foto's". Dutch only: remove one file. frontend/src/i18n/locales
18 Phase A built (2026-11-17, on assumptions): what is in the first step? Read-only only: the usage contract (IMediaUsageProvider, MediaLibraryService, pure CleanupSelection), the Hero provider and the selection components in the frontend (PhotoSelectionList, BulkActionBar, selection rules). No endpoint, no screen, no delete, no migration, no address change yet. Wire the screen and endpoints next (list, storage, clean-up preview) and then delete (needs a Hero delete path and Bryan's check of assumptions 3, 7 and 10). Core/Media/Library, Modules.Hero/Services/HeroMediaUsageProvider.cs, frontend/src/features/media
19 The position of a slide in "Hero, slide 3". [Confirmed by Bryan "as designed", 2026-11-17] Rank by SortOrder within its hero, counting slides that are switched off, 1-based; a slide that is off still counts as a use and is shown "(uit/off)". Count only active slides, or show the slide's title instead. HeroMediaUsageProvider.ListUsesAsync
20 The thumbnail of a Hero photo in the library. [Confirmed by Bryan "as designed", 2026-11-17] The smallest published WebP variant of the current set; none yet (a grey "no preview") while the set is not cut. Use the full-frame preview (full-*.webp), which shows the whole picture instead of the wide crop. HeroMediaUsageProvider.Thumbnail
21 A name for a photo. [Decided by Bryan, 2026-11-17, second round: see "Decisions of the second round"] Photos have no file name today (HeroImage does not store it), so the library shows a neutral label (date and size); a name field comes with the library's own tables (phase B). Store the original file name at upload now (a small Hero migration, additive). PhotoItem.name, phase B
22 Select all and ranges with photos that cannot be selected (in use during a clean-up). They are skipped by "select all" and by shift-ranges; the header box shows "some" when only part is selected. Include them but refuse at confirmation. PhotoSelectionList, selection.ts
23 Where does Hero list all photos (performance)? In memory, newest first, as the rest of the Hero repository does (a few dozen photos; the MySQL provider has limits with Guid lists). Paging comes with the screen when the count grows. Server-side paging by CreatedAt (needs an index). HeroRepository.GetAllImagesReadOnlyAsync
24 Tile ratios of the ASF mosaic (assumption 1). Answered by the ASF session (2026-11-17, from its code): the mosaic shows at most 4 tiles per shoot page, from 2 photos up (layouts for 2, 3, 4). The tile shape is fixed per page by the photo count and order, not chosen per photo: large (photo 1) 2x2, desktop about 1:1 (max about 656x632), phone 4:3; wide (photo 2 with 3 or 4 photos) 2x1, desktop about 2.2:1 (max about 656x300), phone 3:2; small (photos 3 and 4 with 4 photos) 1x1, about 1.04:1 (max about 312x300), phone 1:1. With 2 photos: two large side by side. All object-fit cover (a crop). Widths: large and wide up to about 656 px, small about 312 px; phone half width about 175-300, full width about 350-600; retina variants 480, 640, 960, 1280. Masonry (portfolio): natural ratio only, no crop (rounding below half a row of 1/40 of the column width); 1, 2 or 3 columns, column width up to about 427 px; thumb now 800 px wide with the height following the ratio, variants about 480 and 800; the lightbox uses a separate full. Used in the design as uses mosaic-large, mosaic-wide, mosaic-small (each with a focus point and a desktop and phone shape) and masonry (no crop). Each answer only adds use definitions. A ratio per photo (not per tile shape) would need a ratio editor. Application design section 4
25 Use definitions in code (built 2026-11-17, pure data, nothing consumes them yet). MediaUseDefinition (ratios with widths, or natural) and GalleryUses for the ASF needs: mosaic-large (tilelarge 1:1, tilelargem 4:3), mosaic-wide (tilewide 11:5, tilewidem 3:2), mosaic-small (tilesmall 26:25, tilesmallm 1:1), masonry (natural, no crop). Ratio names are letters only (2 to 10) to fit the address allow-list, so a phone shape is a name with an m suffix. Widths: large and wide 480, 640, 960, 1280 (retina set from the ASF answer); small 312, 480, 640; masonry 480 and 800. The set hash uses the shared MediaPaths.SetHash formula (a test shows it equals the Hero's). Hero's own wide (3:2) and tall (4:5, not the 2:3 the first design sketch said) stay as built in VariantPlanner. Other widths or ratio values change only the definitions; the ASF full (lightbox) variant is not defined yet (it is the full-frame preview ratio). Core/Media/Library/MediaUseDefinition.cs
26 Choose or upload everywhere (ML-17): how does the Hero upload relate to the library? [Confirmed by Bryan "as designed", 2026-11-17] Now the Hero keeps its own upload and table; its photos are already in the library list through the provider. When the library owns uploads (phase B) every upload creates exactly one library record (same file = same record by hash). The Hero switches to the shared picker with the phase C migration. Until then the Hero upload flow does not change. Moving the Hero to the picker earlier (before phase B) would give a single upload path sooner but touches the Hero flow and needs the data model first. Application design section 10
27 Scope of the shared picker: single choice or several, and what does it include? [Confirmed by Bryan "as designed", 2026-11-17] One photo per picker (single choice, radio group). It includes the library photos and one upload button (one file at a time); the Hero's multi-file upload and drag and drop stay on the Hero screen. The picker is pure: the module passes the list and the upload callback. Several photos at once or drag and drop in the picker: a larger component, added when a module needs it (the gallery will probably need multiple). features/media/components/ImagePicker.tsx
28 Uploaded photo not ready yet in the picker. [Confirmed by Bryan "as designed", 2026-11-17] It is chosen at once but shows "no preview" until the background renderer has cut its set; an image without a set is not published (as in the Hero today). Block choosing until it is ready: simpler to explain, slower to work with. ImagePicker, HeroRenderService

Decisions of the second round (Bryan, 2026-11-17, via SLP Software - SLS - Main)

# Decision Consequence in design and code
3 The automatic removal of unused Hero uploads is switched off once Bryan has approved the screen (PR #22). Media:AutoCleanupUnattached keeps its default true; it becomes false only at or after his approval of PR #22.
4 One shared library for Owner and Administrator, no rights per module. As designed (AdminOnly).
7 A photo used only by a switched-off slide counts as used. As designed (HeroMediaUsageProvider reports it as a use with Active = false).
8 The clean-up period counts from the last use, not the upload date. Each photo gets "unused since" (the moment it was last detached from a slide; the upload date when it was never used). Details in assumption 29.
10 Deleting a photo that is in use is possible after a second confirmation that names the places. Delete refuses an in-use photo unless the request says it was confirmed twice; the module detaches it (Hero: the slides using it are removed). Assumption 30.
12 There is a trash: recoverable for 7 days (DeletedAt plus the existing retired-file mechanism). Delete means "to the trash"; the files go 7 days later. A trash view lists them with Restore. Assumption 31.
13 The migration of HeroImages to the library's own tables may be built next (expand then contract, same ids, hashes and addresses). Conditions: document a back-up and rollback plan first; roll out only to TEST, never production; tell SLS-Main before deploying to test. Assumption 32.
21 The original file name is stored at every upload from now on (additive); existing photos keep the neutral label. OriginalFileName on the Hero image (additive migration); the library shows it.

New assumptions from these decisions

# Question Assumption made If Bryan chooses differently Where
29 Reference date of the clean-up (decision 8). For a photo that is not in use: the moment it was last detached from a slide (LastUsedAt), else its upload date. For a photo that is in use right now (clean-up with "Only unused photos" off): its upload date, since "last used" is "now" and nothing would ever be old enough. The period slider keeps its range (1 to 365 days, default 7). "Last used" for a photo in use = the last save that kept it, so with the filter off only photos left alone for the whole period are offered. HeroImage.LastUsedAt, HeroService.SaveAsync, CleanupSelection
30 Detaching a used photo when it is deleted (decision 10). In the Hero the slides that use the photo are removed from the hero (a slide cannot exist without an image); the second confirmation names them ("Hero, slide 3"). The hero then has fewer slides and stays published as long as it has a title. Keep the slide and mark it "image missing" until a new image is chosen: needs a nullable slide image and a changed public contract. HeroMediaUsageProvider.TrashAsync
31 Trash mechanics (decision 12). DeletedAt on the Hero image: a trashed photo is hidden from the Hero (slides, upload by hash, renderer) and shown in the library trash; Restore clears it. After 7 days the cleanup turns it into retired files (removed immediately) and removes the row. Uploading the same file again restores it. The trash period is Media:TrashDays (7). Another period: the setting; no trash: delete straight to retired files. HeroImage.DeletedAt, HeroMediaCleanup, MediaOptions.TrashDays
32 Migration of HeroImages (decision 13): the plan and the safeguards. Designed in inception/application-design/migration-plan.md (back-up, rollback, verification, test-only rollout). The additive columns of this round (OriginalFileName, DeletedAt, LastUsedAt) are copied with the rest. Not run anywhere until SLS-Main has been told and agrees to the test deploy. n/a migration-plan.md

Status of the assumptions (2026-11-17)

  • Decided by Bryan (second round, table above): 3, 4, 7, 8, 10, 12, 13, 21.
  • Confirmed by Bryan "as designed": 1, 2, 5, 6, 9, 11, 14, 15, 16, 19, 20, 26, 27, 28.
  • Still assumptions (not put to him separately): 17 (language), 18 (what phase A contained, now overtaken), 22 (selectability), 23 (performance), 24 (ASF data), 25 (use definitions); and the older rows 18 to 25 above. Assumptions 29 to 32 follow from his decisions.
  • Assumption 12 now reads: there IS a trash (decision 12), the earlier "no trash in phase A" no longer applies. Assumption 10: deleting a used photo is possible after a second confirmation (built). Assumption 21: the original file name is stored from now on (built).