Files

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.

  • SetHash of a use is computed by the existing MediaPaths.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 Hero Variants list 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's wide and tall exist 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 wide and tall crops, 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)

  1. Back-up the database and the media directory.
  2. Create MediaAsset and MediaUse (additive migration). No existing table changes.
  3. Copy: one asset per HeroImage with 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.
  4. Switch Hero reads to the library behind a setting; keep the old columns written for one release (expand), then drop them (contract).
  5. 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 shared Checkbox, shift-click range, select all and clear, aria-live count.
  • 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 same PhotoSelectionList preselected, 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.