8.7 KiB
Application design (draft on assumptions): media-library
Status: draft, built on assumptions-and-open-questions.md. Nothing here moves data or changes public addresses.
1. Components
graph TD
UI[Admin: Media library screen] --> API[MediaLibraryController]
UI --> SEL[Selection + BulkActionBar components]
API --> LIB[MediaLibraryService]
LIB --> USE[MediaUsageService]
LIB --> STO[MediaStorageUsage]
LIB --> STORE[IMediaStore]
USE --> PH[Hero IMediaUsageProvider]
USE --> PG[Gallery IMediaUsageProvider, later]
PH --> HERO[(HeroImages / HeroSlides)]
HOST[Public /media endpoint] --> STORE
classDef ui fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
classDef core fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
classDef mod fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
classDef data fill:#fbb6ce,stroke:#b83280,stroke-width:1px,color:#000;
class UI,SEL ui;
class API,LIB,USE,STO,STORE,HOST core;
class PH,PG mod;
class HERO data;
Text alternative: the admin screen calls the library service in Core, which asks each module's usage provider where a photo is used and reads files and sizes through IMediaStore; the public media endpoint is unchanged.
| Component | Where | Responsibility |
|---|---|---|
IMediaUsageProvider |
Core (contract), implemented per module | ListUsesAsync(photoKey[]), DetachAsync(photoKey), ListPhotosAsync(paging) (phase A read-through) |
MediaUsageService |
Core | Fans out to all providers, merges uses, knows which modules have no provider |
MediaLibraryService |
Core | Listing (newest first), delete orchestration, clean-up preview |
MediaStorageUsage |
Core | Bytes of originals plus variants, cached 60 s, warning level |
CleanupSelection |
Core, pure | Given photos, uses, now, days and the unused flag: the preselected set |
MediaLibraryController |
Core or new module (see 7) | GET /api/v1/media, GET /api/v1/media/storage, POST /api/v1/media/cleanup/preview, POST /api/v1/media/delete |
Frontend features/media |
frontend | Screen, PhotoSelectionList, BulkActionBar, CleanupDialog, StorageMeter, React Query hooks |
2. Data (target, phase B and later; phase A uses Hero data read-only)
erDiagram
MediaAsset ||--o{ MediaUse : "is used by"
MediaAsset {
guid Id
string OriginalSha256
string OriginalKey
int Width
int Height
long Bytes
double DefaultFocusX
double DefaultFocusY
double DefaultZoom
datetime CreatedAt
guid CreatedByUserId
}
MediaUse {
guid Id
guid AssetId
string Module
string Place
string RatioSet
double FocusX
double FocusY
double Zoom
string SetHash
}
Text alternative: one photo (MediaAsset) has many uses (MediaUse); each use has its module, place, ratio set, its own crop and the set hash derived from the photo hash plus that crop.
SetHashof a use is computed by the existingMediaPaths.SetHash(OriginalSha256, crops); for a Hero slide this equals today's value (verified by a test in phase A against current golden data).- Variants stay files in the store (
/media/{area}/{setHash}/...); no variants table is needed (the HeroVariantslist is derived from the planner and the files). - A use is
Module+Place(for Hero "slide 3", id of the slide), not a free text.
3. Usage contract
public interface IMediaUsageProvider
{
string Module { get; } // "hero"
Task<IReadOnlyList<MediaUse>> ListUsesAsync(IReadOnlyCollection<Guid> photoIds, CancellationToken ct);
Task<IReadOnlyList<MediaPhoto>> ListPhotosAsync(MediaPaging paging, CancellationToken ct); // phase A read-through
Task DetachAsync(Guid photoId, CancellationToken ct); // before the library deletes the photo
Task<bool> DeleteAsync(Guid photoId, CancellationToken ct); // phase A: the module deletes its own photo
}
A MediaUse carries Module, PlaceLabel (for display, translated by the module, for example "Hero, slide 3"), PlaceId and Active. In phase A the Hero provider implements all four members over HeroImages and HeroSlides; from phase B the library owns the photos and ListPhotosAsync/DeleteAsync fall away.
4. Uses and crops
flowchart LR
P[Photo + default focus] --> U1[Use: hero wide]
P --> U2[Use: hero tall]
P --> U3[Use: mosaic tile 4:5]
P --> U4[Use: masonry natural]
U1 --> S1[set hash A]
U2 --> S1
U3 --> S2[set hash B]
U4 --> S3[set hash C]
classDef p fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
classDef u fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
classDef s fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
class P p;
class U1,U2,U3,U4 u;
class S1,S2,S3 s;
Text alternative: one photo has uses in Hero (wide and tall share one set), a mosaic tile and a masonry gallery; each set has its own hash and address.
MediaUseDefinition(code, per module): ratio names, ratio values and widths for the variant planner. Hero'swideandtallexist today; the mosaic's tile ratios and masonry's natural ratio are added by the gallery module.- A natural-ratio use stores no crop (focus ignored); the planner produces widths only.
- The Hero sets are unchanged: one use per slide carrying the image's
wideandtallcrops, one set hash.
5. Delete and clean-up flow
sequenceDiagram
box rgba(246,224,94,0.4) Admin
participant U as Person
end
box rgba(99,179,237,0.4) Core
participant L as MediaLibraryService
participant S as MediaUsageService
end
box rgba(154,230,180,0.4) Module
participant P as Usage provider
end
U->>L: Clean-up preview (days, only unused)
L->>S: Uses of all photos in the period
S->>P: ListUsesAsync
P-->>S: Uses
L-->>U: Newest first, all selected, bytes to free
U->>L: Confirm selected ids
L->>S: Re-check uses
L->>P: DetachAsync / DeleteAsync
L->>L: Delete files in the store
L-->>U: Result per photo
Text alternative: the person previews, the service re-checks usage at confirmation time (a photo used since the preview is skipped), the module detaches and deletes, the service removes files and reports per photo.
- The re-check at confirmation protects against a photo that became used after the preview.
- Bulk delete is limited (100 photos per request), idempotent and reports per photo.
6. Migration outline (phase C, designed only)
- Back-up the database and the media directory.
- Create
MediaAssetandMediaUse(additive migration). No existing table changes. - Copy: one asset per
HeroImagewith the same id, hash, key and set hash; one use per slide that references it. A verification query compares counts, ids and set hashes and aborts on any difference. - Switch Hero reads to the library behind a setting; keep the old columns written for one release (expand), then drop them (contract).
- Rollback until step 4: delete the new tables (no consumer changed).
7. Module placement (assumed)
The model and services live in Core (SlpModularCms.Core.Media, next to the store) so Hero and the gallery module depend on Core only; the controller and the EF tables (phase B) go in a new module SlpModularCms.Modules.Media with its own DbContext and migrations, like the other modules, and a test project under Tests/Modules. Phase A needs no new tables, so the first controller can ship in the Hero-independent Core registration.
8. Frontend
PhotoSelectionList: virtualised or incremental list of cards (thumbnail, name, size, date, usage chips), with the sharedCheckbox, shift-click range, select all and clear,aria-livecount.BulkActionBar: sticky, shows the count and the actions; actions are data ({id, label, destructive, run}) so tags or move can be added.CleanupDialog: slider (days),CheckboxField"Only unused photos" (default on), the samePhotoSelectionListpreselected, summary of count and bytes, confirm.StorageMeter: used, limit, warning colour plus text.- Sidebar entry "Mediabibliotheek" for Owner and Administrator.
9. Test strategy
- Pure:
CleanupSelection(age, unused flag, ordering), range selection, set-hash per use equals the Hero value (property tests). - Service: delete re-check, partial failure, limit of 100, in-use rules, storage warning thresholds.
- Hero provider: uses per slide, detach.
- Regression: golden files and the host-injection tests unchanged; a set made before the library is still served.
- Frontend: selection by mouse and keyboard, announcements, dialog flow, i18n nl and en.