Drag a photo into the media library and it's "done" in a heartbeat. That heartbeat is a small lie of presentation: the real work — resizing, reformatting, poster-framing, the dance that makes one file servable on every page and screen — happens after you've walked away. This post traces what actually happens between "upload complete" and "ready everywhere," and the two or three design decisions in that gap we'd defend anywhere.

Accept fast, process later

The first decision shapes everything: the upload path does the minimum. Receive the file, store the original, create the media record with status: processing, return. Everything expensive — decoding, resizing, transcoding — is deferred to background processors, because the human at the keyboard is the scarcest resource in the pipeline and nothing they're waiting on should ever include "transcode a video."

The status field is the contract with the UI: processing means "yours, safe, being prepared," and the library can show the asset immediately while its variants materialize. The original is sacred and untouched — every derived rendition is exactly that, derived, which means reprocessing is always possible and a bad transcode never costs the source.

Variants: one original, many faces

Why variants at all? Because the file a camera produces and the file a webpage should serve are different artifacts with different jobs. A modern phone photo is several thousand pixels wide and multiple megabytes; the card it appears in on someone's phone screen is 400 pixels wide on a coffee-shop connection. Serving the original everywhere is how sites get slow, and slow is its own accessibility failure.

And when a placement needs something the standard ladder doesn't cover, custom variants are generated on demand: an exact width, a format from a short menu (webp, jpg, png), resampled with a quality filter rather than a fast one. The menu is the point — the same sizes-from-a-menu discipline as type scales, applied to pixels: a constrained set of good options beats infinite mediocre ones, for humans and for the AI placing images into pages.

One contract, two pipelines

Image processing and video processing are different beasts — different libraries, different costs, different failure modes — and the obvious architecture gives each its own integration. We deliberately didn't: both pipelines share the exact same payload shape and webhook contract. One invoker dispatches to either processor; one receiver handles either's results. The processor's name is the only thing that changes.

The reasoning is anti-drift: two integrations that start identical never stay identical — each accumulates its own retries, its own error shapes, its own folklore, until "fix the webhook handling" is two tickets. Sharing the contract means improvements land on both pipelines by construction, and adding a third media type someday is a new processor, not a new integration. It's the helpers argument again: centralize the part you'll need to fix.

The race we had to respect

Here's the bug-shaped corner, and regular readers will recognize the family. The processor finishes and posts its results — variants, metadata, the new status — to a completion webhook. But the media record it's patching was created by an upload whose own write may still be propagating between instances. Occasionally the webhook arrives before the record is visible. The naive receiver looks up the record, finds nothing, drops the payload — and the asset is stuck in processing forever, because the processor reports exactly once and never re-posts.

The fix is the patient receiver: a result that finds no record isn't an error, it's an early arrival — so the patch is queued and re-applied with backoff until the record appears or attempts genuinely run out. The general lesson sits right beside our distributed-writes postmortem: when a callback fires at most once, the receiving side owns the persistence. You can't ask the one-shot caller to be patient, so the receiver must be — and "not found yet" must be a different code path than "not found."

Placement: reference, never copy

The last leg is where media meets pages, and the rule is one we've preached from the product side: pages and posts reference library assets, they don't embed copies. One upload, many placements — and the consequences compound quietly:

• Metadata travels. The description written once in the library — the alt text, the tags — arrives at every placement, instead of being retyped or skipped per page.
• Replacement is an edit, not an audit. The updated logo, the reshot product photo: change the asset, every placement follows. The five-times-uploaded image is the document fork wearing a JPEG extension, and references are how it never forks.
• The right variant per placement, automatically. Because placements reference the asset rather than a file, the render path can choose the appropriate rendition for the context — the hero gets the big one, the card gets the small one, nobody chooses by hand.

What we'd carry to any media pipeline

• Never make a human wait on a transcode. Accept, record, defer — the status field is the UI contract.
• Keep originals sacred. Everything derived must be re-derivable; a processing bug should cost compute, never content.
• Share contracts across media types. The payload and webhook shape is the part that drifts — make it singular.
• Receivers own persistence for one-shot callbacks. "Not found yet" is a retry, not a drop.
• Constrain the variant menu. A short list of good formats and quality resampling beats infinite knobs.
• Reference, never copy. Identity for assets, like identity for customers — one record, many appearances.

Frequently asked questions

The media pipeline ships inside Faster — upload once, place everywhere, with the right pixels chosen for you. More engineering notes: the engineering blog.