Skip to the content.

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

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)

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. Security granularity. A shared Bearer gate is implemented; user-specific identity, role permissions and tenant isolation were not established by this review.
  7. 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.

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