Architecture

Media Inspector is an infrastructure-grade media intelligence platform that inspects public URLs and produces richly structured, semantically governed metadata responses.

Core Design Principles

The platform is built around four architectural invariants:

1. Progressive Enrichment

Resources evolve through enrichment stages over time. An initial request returns whatever intelligence is immediately available. Background workers continue enriching the canonical resource asynchronously.

Request 1 (FAST) → semantic + mediaFormat completed     → partial
                  ↓ background workers
Request 2 (FULL) → + preview + palette + metadata       → complete

Enrichment completion is monotonically non-decreasing — enrichments never regress. Once a stage is marked completed, it remains completed across all subsequent requests, regardless of profile or cache state.

2. Projection Profiles

Profiles are a pure view layer. They control payload visibility — not orchestration.

Profile	Latency	Payload Richness	Behavior
fast	Minimal	Lightweight projection	Omits heavy fields, returns immediately
standard	Progressive	Async enrichment visibility	Returns partial with 202 Accepted for heavy media
full	Deterministic	Maximum metadata richness	Blocks until all enrichments complete

Profiles never mutate orchestration state, processing lifecycle, or canonical enrichment registry.

3. Provider-Native Intelligence

The platform distinguishes between provider-native and generated intelligence:

• Provider-native: Data sourced directly from the content provider (e.g., YouTube thumbnail URLs, oEmbed titles)
• Generated: Data computed by the platform's enrichment pipeline (e.g., blurhash placeholders, palette extraction)
• Extracted: Data read from the media binary itself (e.g., codec detection via ffprobe, image dimensions)

Enrichment provenance is immutable — the enrichmentSources record always reflects where data was originally produced, even when served from cache.

4. Schema Governance

Every response is governed by strict serialization rules:

• Empty objects are forbidden — {} is never a valid response value
• null means known-but-unavailable — the enrichment is supported but hasn't completed yet
• Omission means unsupported — the field doesn't apply to this media category
• Every namespace carries semantic meaning — if a namespace exists, it has content

Request Lifecycle

Client Request
  → URL validation & SSRF protection
  → Cache lookup (canonical raw state)
  → Semantic analysis (provider detection, kind classification)
  → Media format detection (MIME, container, codec)
  → Enrichment orchestration (profile-dependent wait behavior)
  → Schema formatting (profile projection, field filtering)
  → Response serialization (empty object removal, null semantics)

Canonical State Model

The platform maintains a single canonical raw state per resource. All profiles project from this shared state:

Canonical Raw State
  ├── FAST projection   → lightweight view
  ├── STANDARD projection → progressive view
  └── FULL projection   → complete view

This means:

• FAST and FULL for the same URL share the same orchestration job
• Cache stores canonical state, not profile-specific snapshots
• Profile switching never corrupts the underlying resource data

Next Steps

• Quick Start — make your first request
• Projection Profiles — understand FAST, STANDARD, and FULL
• Progressive Enrichment — lifecycle behavior