Skip to the content.

Media Library — current implementation

Source review: 2026-10-20, HEAD f38ee3c6ced7fcab6b34955a65cfb955ec097567, root package 1.6.9. This page supersedes the October 14 diagrams for current behavior. Each edge below follows the linked implementation; conditional paths are labeled. It is a source review, not a live deployment check.

2026-11-05 deletion update: deleteAsset records an asset.delete_started audit plan before the catalog cascade, keeps the name held during object removal, and resumes a failed or interrupted delete when the same ID is deleted again. The deletion sequence and risk note below reflect the current code at 3c6086c04. Sources: delete workflow, recovery tests.

Components

flowchart LR
  UI["core/admin media UI"] --> AC["media-client"]
  AC --> AR["admin media routes"]
  AR --> AS["admin media-service"]
  AS -->|local| ML["MediaLibrary"]
  AS -->|MEDIA_API_URL| NR["media-nuxt routes"]
  NR --> MA["media-auth principal and scope"]
  MA --> SL["scoped MediaLibrary"]
  SL --> ML
  ML --> CAT["CatalogStore / JobStore / AuditStore"]
  ML --> BLOB["BlobStore"]
  ML --> IMG["image transformer / sanitizer"]
  CAT -->|local| SQL["SQLite"]
  CAT -->|Dynamo backend| DDB["DynamoDB"]
  BLOB -->|local| FS["filesystem"]
  BLOB -->|Dynamo backend| S3["S3 or MinIO"]
  S3 -->|AWS ObjectCreated under m/| SQS["SQS media queue"]
  SQS --> WORKER["media worker"]
  WORKER --> ML

The admin server sanitizes forwarded uploads before presign; its local library injects the full sanitizer. Web routes inject the web sanitizer and use getScopedMediaLibrary; the worker is a trusted unscoped caller. Tenant-token parsing exists, but verifyMediaTenantToken returns null, so tenant Bearers currently receive 401. The admin token remains the usable HTTP principal. The admin database selector does not select the DAM store. Sources: admin media service, web media auth, tenant-token verifier, web library factory, worker, SAM resources.

Domain and ports

classDiagram
  class MediaAsset {
    +string id
    +MediaTenant tenant
    +MediaKind kind
    +string path
    +string sha256
    +number byteSize
    +Record meta
  }
  class MediaChild {
    +string id
    +string assetId
    +MediaChildVariant variant
    +ChildStatus status
    +string path
  }
  class JobRecord {
    +string id
    +string assetId
    +string childId
    +JobStatus status
    +number attempts
  }
  class AuditEvent {
    +string entityId
    +string action
    +string correlationId
  }
  class MediaLibrary {
    +ingest(input)
    +registerRemoteAsset(input)
    +renameAsset(id, request)
    +runMaterializeJob(id)
    +deleteAsset(id)
  }
  class CatalogStore {
    <<interface>>
    +insertAsset(asset)
    +renameAsset(input)
    +deleteAssetCascade(id)
  }
  class BlobStore {
    <<interface>>
    +put(key, data, options)
    +get(key)
    +delete(key)
  }
  class JobStore {
    <<interface>>
    +claimQueuedJob(id, claimed)
    +finalizeRunningJob(id, startedAt, next)
  }
  class AuditStore {
    <<interface>>
    +append(event)
  }
  MediaAsset "1" --> "0..*" MediaChild : assetId
  MediaAsset "1" --> "0..*" JobRecord : assetId
  MediaChild "1" --> "0..*" JobRecord : childId
  MediaLibrary ..> CatalogStore
  MediaLibrary ..> BlobStore
  MediaLibrary ..> JobStore
  MediaLibrary ..> AuditStore

These are implemented TypeScript types and the concrete MediaLibrary class. Audit events reference entities by ID but have no enforced relational association, so no association is drawn. CatalogStore, BlobStore, JobStore, and AuditStore are injected ports; SQLite, filesystem, DynamoDB, and S3 are adapter implementations. The SQL and Dynamo catalogs implement name claims, rename, and conditional child/job writes differently. Sources: domain types, ports, library, SQLite stores, Dynamo stores, PostgreSQL adapter.

Upload and validation

sequenceDiagram
  actor Operator
  participant Admin as Admin UI and service
  participant API as media-nuxt ingest routes
  participant Scope as Media principal and scoped library
  participant Store as Reserved catalog and blob store
  Operator->>Admin: Choose file and metadata
  alt Admin uses local media library
    Admin->>Store: MediaLibrary.ingest with full sanitizer
    Store-->>Admin: Registered asset
  else Admin forwards to media API
    Admin->>Admin: Sanitize supported input
    alt SVG
      Admin->>API: POST ingest/svg
      API->>Scope: Authenticate and validate scope
      Scope->>Store: Ingest checked SVG
    else Other supported kind
      Admin->>API: POST ingest/presign with byteSize
      API->>Scope: Authenticate, validate kind and tenant
      Scope->>Store: Reserve name
      API-->>Admin: Signed PUT URL and headers
      Admin->>Store: PUT exact bytes
      Admin->>API: POST ingest/complete
      API->>Scope: Authenticate and check reservation
      Scope->>Store: Head, digest, sanitize if needed, register
    end
    Store-->>Admin: Asset and URLs
  end
  Admin-->>Operator: Asset or mapped error

The admin upload route receives base64 JSON and decodes into a buffer. Forwarded SVG uses its own authenticated route; other kinds use presign/PUT/complete. The presign route checks declared size against per-kind caps; tenant requests require byteSize and are limited to raster types, though tenant tokens are presently disabled. complete checks the reservation and stored object, computes its digest, applies conditional in-place raster sanitization where needed, and registers the result. A repeated completion for an already registered asset returns it without re-sanitizing. PDF/MP4 preSanitized signatures have a compatibility mode: missing signature or key may still be honored for an admin request, as described in the route; this is not a fully enforced signature requirement. Sources: admin upload, admin upload route, presign, complete, SVG route, sanitizer, upload caps, upload lifecycle.

Processing

sequenceDiagram
  participant Caller as Request or worker
  participant Library as MediaLibrary
  participant Jobs as JobStore
  participant Transform as ImageTransformer
  participant Blobs as BlobStore
  participant Catalog as CatalogStore
  Caller->>Library: Materialize or re-run recipes
  Library->>Jobs: Insert and claim job
  Jobs-->>Library: Lease
  Library->>Blobs: Read original
  Library->>Transform: Run image recipe
  Transform-->>Library: Output bytes and metadata
  Library->>Blobs: Put deterministic variant key
  Library->>Catalog: Conditionally finalize job and child
  Catalog-->>Library: Updated, moved, missing or lost lease
  Library-->>Caller: Current child and job

On ingest, metadata and image catalog variants (t, 640, 1280, 1920) are attempted by the request hook except when the AWS queue owns the work. Explicit materialization uses SQS when MEDIA_QUEUE_URL is configured and otherwise runs inline. The S3 ObjectCreated notification also feeds the queue, and the worker waits briefly for registration if the event wins the race. Only the image transformer is implemented; other transform recipes remain unsupported. Output is still written to a deterministic key before lease-conditioned catalog finalization. Rename-aware retries reduce moved-asset races but do not make blob publication atomic. Sources: on-ingest recipes, dispatch, worker, materialize runner, transformer registry, SAM queue and trigger.

Retrieval, editing, renaming and deletion

sequenceDiagram
  actor Operator
  participant UI as Admin media page
  participant API as Admin or web media route
  participant Library as Scoped or local MediaLibrary
  participant Catalog as CatalogStore
  participant Blobs as BlobStore
  participant Audit as AuditStore
  Operator->>UI: Open asset
  UI->>API: GET asset detail
  API->>Library: getAsset and listChildren
  Library->>Catalog: Read catalog
  Catalog-->>UI: Asset, children, jobs, processing and URLs
  opt Edit details or tags
    UI->>API: PATCH metadata
    API->>Library: updateAssetMeta with edit validation
  end
  opt Rename file
    UI->>API: POST rename
    API->>Library: renameAsset
    Library->>Blobs: Copy to new keys
    Library->>Catalog: Atomic name and row switch
    Library->>Blobs: Remove old keys
  end
  opt Delete asset after UI Undo window
    UI->>API: DELETE asset
    API->>Library: deleteAsset
    Library->>Audit: Record delete_started with object paths
    Library->>Catalog: Cascade asset and children, hold name
    Library->>Blobs: Delete recorded object keys
    alt object delete fails or process stops
      Library->>Audit: Record delete_failed if process survives
      Operator->>API: Repeat DELETE with the same asset ID
      API->>Library: resumeDelete from audit plan
      Library->>Blobs: Retry remaining object keys
    end
  end

Catalog reads are authenticated. Public /m/** or CloudFront object delivery is separate and has no admin Bearer check. Admin details and tag editing use explicit forms; metadata PATCH validates human edits, while internal measured-metadata writes use a separate path. Rename changes public keys and has no redirect from old URLs. The catalog switch is atomic within an adapter; copy and cleanup span storage, with audit-led resumption on later reads/renames. Delete rejects fresh running jobs. Its audit plan and name hold make a repeated delete of the gone ID recover failed object removal and invalidation; no scheduled sweep of open plans is implemented. Sources: admin editing, rename UI, admin service, scoped library, rename workflow, delete workflow, local delivery, URL projection.

Lifecycle and deployment

flowchart TD
  Select["Select file and metadata"] --> Validate["Validate kind, size and sanitize"]
  Validate --> Reserve["Reserve name or ingest locally"]
  Reserve --> Store["Store original and catalog asset"]
  Store --> Recipes["Run or queue on-ingest recipes"]
  Recipes --> Retrieve["List, detail and public object URL"]
  Retrieve --> Edit["Edit metadata or tags"]
  Edit --> Rename["Optional rename with copy, switch and cleanup"]
  Rename --> Process["Optional re-run or custom image variant"]
  Process --> Delete["Optional delete after client Undo window"]
  Delete --> Cascade["Catalog cascade then object removal"]
flowchart LR
  Host["Host admin node-server"] --> LDB["Admin SQLite and filesystem media"]
  Docker["Docker admin or development"] --> Emu["DynamoDB Local and MinIO"]
  Docker --> PG["PostgreSQL for posts and messages"]
  Web["Web Nitro runtime"] -->|DATA_BACKEND sqlite or postgres| WLocal["SQLite and filesystem media"]
  Web -->|DATA_BACKEND dynamodb| Emu
  Lambda["SAM web Lambda"] --> AWSDB["DynamoDB media table"]
  Lambda --> AWSS3["Private S3 assets bucket"]
  AWSS3 --> Queue["S3 notification to SQS"]
  Queue --> Worker["Media worker Lambda"]
  AWSS3 --> CF["CloudFront OAC delivery"]

The PostgreSQL media catalog adapter exists as a package, but getMediaLibrary still falls back to SQLite/filesystem when DATA_BACKEND=postgres outside Lambda. The admin’s own media library stays local unless MEDIA_API_URL is configured; the admin database selector controls posts/messages, not this media backend. AWS Lambda always uses DynamoDB/S3. Docker test emulates Lambda with local AWS services; it does not prove CloudFront behavior. Sources: media factory, admin factory, Compose, SAM template, PostgreSQL media adapter.

Verified gaps and recommendations

Current mechanism Consequence or proposed improvement
Tenant tokens are classified but verifyMediaTenantToken always returns null. Tenant access is not live; implement and test a token map before describing multi-tenant HTTP access as enabled.
Presigned bytes occupy their final public key before complete sanitizes and registers them. A pending object may be retrievable by key; consider private staging or a delivery check before claiming that invalid bytes were never public.
Missing PDF/MP4 pre-sanitization signature can be honored for an admin request in compatibility mode. Decide when to enforce signatures and test key rotation before treating this as a hard trust boundary.
Variant writes use deterministic keys before conditional job/child finalization. Consider attempt-specific storage keys with a compatible public URL contract.
Delete records intent and object paths before catalog removal, but recovery requires a repeated DELETE for the gone ID. Consider an authenticated recovery view or scheduled sweep for abandoned plans; retain the name-hold ownership checks.
Rename has audit-led retry on later reads, but no scheduled reconciler is evidenced. Define retention and a reconciliation trigger for abandoned cleanup if required.

The operational risks are inferences from code paths, not reproduced incidents. For the November correction, the focused media deletion test passed; browser flow, live stores, Docker, AWS, IAM policy behavior and accessibility were not exercised.