Media Library architecture
Current source review (2026-10-21): Media Library — current implementation. The diagrams below remain the October 14 historical snapshot.
Historical snapshot: these diagrams describe the October 14 checkout. Later changes include on-ingest recipes and an extracted materialize runner; source anchors and processing details below need a full refresh before use as current implementation guidance. The October 17 admin proposal records the limited recheck and remaining media design decisions.
Source review: 2026-10-14 (America/Los_Angeles). Repository HEAD: 029399ec3d8144ae824a024c86891b3bff44e801. Root package version: 1.3.73.
This is an as-built review of local source, not deployment certification. Existing unrelated edits in core/admin/app/components.d.ts and theme/core/src/colors.json were left untouched. No application behavior, credentials, live data or Git history was changed.
Architecture summary
The admin Media Library begins at core/admin/app/pages/admin/media/index.vue. It uses createMediaApiClient with the admin session and Vue component state. Its server routes delegate to media-service: either a local MediaLibrary or HTTP forwarding to the web app’s media-nuxt routes. MediaLibrary coordinates injected catalog, blob, job, audit and transformer ports. Local factories select SQLite and filesystem; AWS factories select DynamoDB and S3. SQS is an optional dispatch path configured by SAM. media-player is a separate playback library; its presence in the workspace does not establish a DAM dependency.
Diagrams and traceability matrix
Mermaid source is embedded in Markdown, matching the established architecture documentation convention. Each page contains its supporting files, symbols and source line anchors. Component/deployment/activity views use Mermaid flowchart notation to express UML concepts; class and sequence views use native Mermaid syntax. These are not formal UML/XMI artifacts.
| Diagram | Supporting symbols | Evidence |
|---|---|---|
| Component relationships | createMediaApiClient; export function createMediaApiClient; export async function ingestMediaUpload; export default defineNuxtModule; ‘@tgmc/media-nuxt’; export function getMediaLibrary; export function createMediaLibrary; export function createAwsMediaLibrary; export class ImageTransformer; import { TgmcPlayer | Per-file evidence below diagram |
| Class and domain model | export type MediaAsset; export type BlobStore; export function createMediaLibrary; export class SqliteCatalogStore; export function createAwsMediaLibrary; export class DynamoCatalogStore; const SCHEMA; export function assetPk; export class ImageTransformer | Per-file evidence below diagram |
| Upload sequence | createMediaApiClient; export function createMediaApiClient; export async function ingestMediaUpload; export default defineEventHandler; export async function createPresignedIngest; export function verifyLocalPut; export default defineEventHandler; async reserveName(; async ingest(; async registerRemoteAsset(; export async function ensureDefaultThumbnail; export const requireAdminToken | Per-file evidence below diagram |
| Variant processing sequence | export async function materializeOrEnqueue; export async function ensureDefaultThumbnail; async runMaterializeJob(; export class ImageTransformer; export async function transformImage; export async function mediaWorkerHandler; export function createAwsMediaLibrary | Per-file evidence below diagram |
| Catalog and media retrieval sequence | export async function ingestMediaUpload; export async function withMediaAssetUrlsList; export function getMediaLibrary; export function createLocalMediaCdnHandler; export const requireAdminToken; MediaWorkerFunction: | Per-file evidence below diagram |
| Deletion sequence | createMediaApiClient; export async function ingestMediaUpload; async deleteAsset(; export class DynamoCatalogStore; export function createAwsMediaLibrary; export const requireAdminToken | Per-file evidence below diagram |
| Media lifecycle activity | export async function ingestMediaUpload; async ingest(; export default defineEventHandler; async runMaterializeJob(; async updateAssetMeta(; async deleteAsset(; export async function transferMedia; export function sanitizeSourceBytes; export async function importSiteMedia | Per-file evidence below diagram |
| Deployment | getMediaLibrary; MediaWorkerFunction; Compose services | Per-file evidence below diagram |
Actual workflows
- Upload: admin JSON/base64 uploads decode in the admin server. Local mode calls ingest; forwarding calls web presign, PUT, complete. Direct API clients can use presign/PUT/complete directly. Names are unique per tenant/kind regardless of extension. Completion rereads the object digest and size; it does not trust a client hash.
- Processing: images automatically attempt the t thumbnail. Explicit materialization validates a catalog variant or custom recipe, creates a pending child/queued job and runs synchronously or sends jobId to SQS. ImageTransformer uses transformImage/sharp. Output metadata belongs to the child; ingestion itself does not extract original dimensions/duration.
- Other kinds: originals can be cataloged and retrieved, but SVG/audio/video/model/document materialization is explicitly unimplemented. FFmpeg availability does not change these registry stubs.
- Site import: scripts/site-media-io.js sanitizes and probes prepared sources; importSiteMedia checks review/policy and digest before transferMedia copies the approved bytes. This separate workflow must not be conflated with admin uploads.
- Metadata update: updateAssetMeta shallow-merges metadata, replaces/normalizes an explicitly supplied tags field, writes the catalog and appends audit.
- Retrieval: authenticated list/detail returns catalog records plus public and preview URLs. Local /m/** or CloudFront serves media bytes separately. Models/documents have no automatic preview.
- Transfer: transferMedia copies original and ready-child objects through ports, preserving identities and paths. It has dry-run, conflict/skip/failure reporting, create-only writes and verification of newly written target objects. Source data, jobs and historical audit are not moved; optional target audit records the copy.
- Deletion: an 8-second client Undo window delays DELETE. The backend blocks a fresh materialization lease, removes catalog records, deletes objects, audits and optionally invalidates CloudFront. There is no server recycle bin.
Local versus AWS
| Aspect | Host / standalone admin local | Docker web/test | SAM AWS |
|---|---|---|---|
| Catalog | SQLite | DynamoDB Local by default | DynamoDB |
| Objects | Filesystem plus sidecar headers | MinIO by default | Private S3 |
| Processing | Inline | Inline in supplied stacks | SQS worker |
| Delivery | /m/**, ETag, byte range, sandbox for active types | MinIO or /m/** for FS override | CloudFront OAC |
| PostgreSQL | Media falls back to SQLite | Same fallback when selected outside Lambda | Lambda forces DynamoDB/S3 |
| Admin | Own catalog unless MEDIA_API_URL | Separate admin Compose service | No admin deployment shown in reviewed SAM |
Authentication, errors and boundaries
requireAdminToken performs fail-closed Bearer validation with timing-safe comparison; catalog reads also require authentication. There is no per-user/tenant authorization policy in the reviewed media gate: tenants are namespaces, not proof of access isolation. Local signed PUT has HMAC/expiry/header validation and a configurable byte limit; S3 PUT signs create-only and content headers. Public object delivery does not require the admin token. SAM scopes worker object permissions to m/* and grants queue/table/invalidation access.
mediaErrorToHttp maps validation to 400, missing data to 404, conflicts to 409, existing create-only objects to 412 and size errors to 413. Unsupported processing is persisted as a failed job. Infrastructure faults can requeue and throw; SQS redrives to DLQ. Automatic thumbnail failure is logged without failing the already completed upload.
Architectural issues (verified mechanisms; consequences are inferences)
- Upload validation asymmetry. Normal ingest/complete does not invoke sanitizeMedia or probeMedia. Local signed PUT has an explicit cap; the admin base64 handler shown has no explicit pre-decode size check. Inference: memory pressure and unvalidated original content need separate treatment. This is not a demonstrated exploit.
- Non-atomic deletion. Catalog deletion precedes blob deletion, audit and invalidation. Inference: an external-store failure can leave orphan objects or stale delivery after catalog removal; retrying by asset ID may encounter not-found.
- Shared variant keys. Worker writes deterministic variant keys before lease-conditioned catalog finalization. Inference: catalog fencing alone cannot guarantee the last object writer still owns the lease.
- Incomplete processing support. Only raster images have a real transformer. Metadata policy enforcement defaults off until upload UI collects required editorial fields; PATCH does not invoke that ingest policy.
- Listing and transfer scale. URL enrichment reads children per image/SVG. Dynamo offset pagination and tag filtering read through results. Transfer buffers object bytes and has no job/audit-history copy.
- Security granularity. A shared Bearer gate is implemented; user-specific identity, role permissions and tenant isolation were not established by this review.
- Recovery gaps. Remote audit failure can leave an uploaded object without a catalog record. Abandoned original cleanup occurs when reserveName reclaims the free name; no scheduled cleanup service is established here.
Several scale/transfer limitations are already tracked in interaction redesign TODO. These findings describe implementation and inferred failure modes, not newly reproduced runtime defects.
Recommended improvements (not existing implementation)
- Unify upload content validation, byte limits and measured metadata across admin and presigned flows; keep site-import review distinct.
- Add durable cleanup/reconciliation records for deletion and abandoned uploads; use attempt-specific objects or storage-level fencing for variant publication.
- Add cursor pagination/batched preview lookup and streaming transfer before scaling large catalogs or videos.
- Implement additional transformers only with explicit format contracts and tests; enforce tenant authorization if independent users are introduced.
Verification and uncertainties
Local source is primary evidence; no private repository content was sent to a diagram service. Nx project discovery succeeded after using a shorter NX_SOCKET_DIR; resolved @tgmc/media targets were inspected. Native-module cache warnings remained. Package identifiers were distinguished from actual imports and runtime factory selection.
Relevant test source reviewed includes packages/media/tests/media.spec.ts (ingest, unsupported audio, hard delete, enqueue, rollback and stale-worker cases), packages/media-nuxt/tests/local-ingest-flow.spec.ts, auto-thumbnail.spec.ts, local-s3-put.spec.ts, asset-urls-routes.spec.ts and media-cdn-route.spec.ts; Dynamo tests cover reservations and conditional finalization. This documentation-only review did not run the application, tests, Docker or AWS, and does not claim runtime, UI accessibility, live IAM or deployment verification. Existing docs/comments were compared with implementation; source wins where scope differs.
Diagram syntax validation is recorded in validation.md. Every diagram was compared against its cited factory, method and branch. Broad arrows group internal calls but introduce no additional service. Optional hooks/queues are explicitly conditional. Relationships absent from evidence are omitted.
Further evidence
- packages/web-layer-admin/server/utils/admin-auth.ts:73 — export const requireAdminToken
- packages/media/src/media-library.ts:323 — async updateAssetMeta(
- packages/media/src/transfer.ts:429 — export async function transferMedia
- scripts/site-media-io.js:98 — export function sanitizeSourceBytes
- packages/media/src/site-import.ts:95 — export async function importSiteMedia
- packages/media/src/transformers/registry.ts:7 — export class ImageTransformer
- packages/media-nuxt/runtime/server/utils/media-asset-urls.ts:26 — export async function withMediaAssetUrlsList
- packages/media/src/media-library.ts:891 — async deleteAsset(