Architecture Deep Dive

If a client's 'create upload session' call times out and it retries, that retry should not necessarily produce a second, unrelated session for the same intended upload. Where the client can supply a stable idempotency key for the creation request, the server can recognize the retry and return the existing session instead of minting a duplicate. Not every implementation supports this, but it's worth designing for explicitly rather than assuming a lost response is harmless.

Every operation against a session — uploading a part, requesting finalize, aborting — must verify the caller still owns that session. A session identifier alone should not be sufficient if it can be guessed or leaked.

INITIATED → UPLOADING → FINALIZING → FINALIZED → PROCESSING is one reasonable lifecycle. The important property isn't the exact state names — it's that the session has an explicit state machine at all, so a client (or an operator) can always answer 'what is actually true about this upload right now' instead of inferring it from side effects.

Each part has a stable identity — typically a part number and, once accepted, a provider-assigned identifier (such as an ETag) that the client must record and later submit at completion time.

A failed or dropped part is retried on its own; parts that already landed are never re-sent. This is the core resumability win over a single-request whole-file upload.

Depending on the client and protocol, parts may be uploaded out of order, in parallel across multiple connections, or with gaps that get backfilled later — not strictly sequentially. A resumable-upload design should let the client discover which specific parts are missing or unconfirmed, rather than assuming resumption always means 'continue from the next sequential index.'

Where the object storage provider supports it, attach a checksum per part (and, at completion, for the whole object) so corruption introduced in transit is caught before the object is treated as durable — rather than discovered later during transcoding or playback.

A client claiming 'all my chunks arrived' is a hint, not a fact. Finalize must verify against the object store's own authoritative multipart/session state — the recorded parts and their identifiers — before treating the object as complete. Trusting only client-reported completeness risks finalizing an object that is actually missing or has mismatched parts.

A repeated finalize call for the same upload_id — because the first response was lost, or the client retried defensively — must not create a second video record and must not schedule a second, independent processing workflow. It should discover the already-finalized state and return the same logical result as the original call.

On success: the original becomes a durable object, the upload session moves to FINALIZED, a video/metadata record is created (or updated) in an early lifecycle state, and a processing workflow is durably scheduled — see Durable Processing Handoff next.

Write the finalized metadata and a durable job row (or outbox event) in the same database transaction. A separate dispatcher reads unpublished job rows and publishes them to the processing queue, marking them published once the publish succeeds. If the dispatcher crashes or the publish is duplicated, the worst case is a duplicate delivery of the same job — which the processing side must already tolerate (see Duplicate Processing Job in Failure & Scale).

Every processing workflow has a stable processing_job_id, an attempt counter, and a source_version reference (which finalized object version it's processing). Retries of the same workflow reuse this identity rather than minting a new one — see Processing DAG for how that identity is used downstream.

If probing itself fails or reports an unsupported/corrupted source, the workflow should route to a terminal-failure or quarantine path rather than proceeding into a transcode stage doomed to fail — see Corrupt Source and Unsupported Codec in Failure & Scale.

Track state at least at the stage level, and ideally per output representation within the transcode stage — so a failure in the 720p output doesn't require silently guessing whether 1080p also failed, and doesn't require re-running stages that already succeeded.

A monolithic 'transcode the video' job conflates unrelated failures (a bad 480p encode profile vs. a genuinely corrupt source), makes partial retry impossible without redoing everything, and makes it much harder to answer 'how much of this video's processing actually succeeded.' See Trade-offs & Decisions -> Monolithic Job vs. Processing DAG for the full comparison.

Producing a '1080p' rendition from a 480p source by upscaling does not add real detail — it just spends compute and storage to produce a larger file with no quality benefit, and can mislead viewers about the video's actual quality. Only include ladder rungs the source can genuinely support, unless a product deliberately chooses otherwise for a specific reason.

Cost generally increases with each additional representation, but the relationship isn't a fixed linear multiplier — codec choice, target resolution, source duration, hardware acceleration, reuse of shared decode work across representations, and available parallelism all affect how much each additional rung actually costs. Treat 'each rendition costs about the same increment' as a simplification, not an engineering fact.

The compression algorithm used to encode/decode the video (and separately, the audio) data — for example H.264/AVC, H.265/HEVC, AV1, or VP9. Different codecs trade off compression efficiency, encode/decode compute cost, and device/browser support.

The file structure that wraps encoded video/audio streams and their metadata — for example MP4, fragmented MP4 (fMP4), or MPEG-TS. Which container/package format is used often follows from the streaming protocol/packaging pipeline in use, not an independent free choice.

The pixel dimensions of the decoded frame — e.g. 1920×1080. Resolution is independent of codec: the same resolution can be encoded in more than one codec.

The target (or actual, for variable encodes) number of bits per second the encoded stream consumes. Two renditions at the same resolution can target different bitrates, trading file size/bandwidth against visual quality.

1) Write every output of a given processing attempt to attempt/version-specific temporary keys, never the final public key. 2) Validate the complete output set. 3) Only once validated, publish immutable, final/versioned keys (new object paths that are never reused or mutated). 4) Atomically update the video's active manifest/metadata pointer to reference the new version. 5) Garbage-collect abandoned attempt artifacts later, once it's safe to do so.

Most object stores provide atomic visibility for a single completed object — readers never see a partially-written individual object. That guarantee does not extend across a multi-object rendition set (many segments plus a manifest); the publication boundary above is what makes the whole set appear atomically consistent, not the object store's per-object guarantee alone.

A manifest must never be published pointing at segments that haven't finished being written and validated. Publishing the manifest is part of the same publication boundary described in Safe Output Publication — it happens only after the segment set it references is complete and validated, and it references the final versioned keys, not staging keys.

Because a reprocess can produce a new version (v2) of a video while the previous version (v1) remains playable, the manifest itself is versioned, and the active-version pointer in metadata decides which manifest a new playback request resolves to. See Video Deletion and Multi-Region Ownership for related version-pointer patterns.

Shorter segments (a few seconds) allow finer-grained quality adaptation and caching at the cost of more requests and per-boundary overhead; longer segments reduce request overhead but adapt more slowly. Any specific duration value is an example for teaching purposes, not a universal standard — real systems tune this per product, and low-latency streaming in particular uses different chunking strategies that are out of scope for this module.

The player picks an initial representation using whatever signals it has before playback starts — estimated throughput, device/display constraints, or a conservative default. This is not necessarily the lowest available quality; it's whatever the player's startup heuristic judges sustainable, which can reasonably start higher on a fast, known-good connection.

Once playing, the player continuously estimates achieved network throughput (typically from recent segment download times), tracks current buffer occupancy, and factors in device/display constraints (no point requesting 4K on a phone-sized player surface). It combines these to choose the representation for the next segment.

Switching representations too eagerly on every small throughput fluctuation produces a visibly unstable, oscillating quality experience. Smoothing/hysteresis logic — requiring a sustained trend before switching, or biasing toward buffer health over instantaneous throughput — keeps quality changes purposeful rather than jittery. See Failure & Scale -> ABR Oscillation.

When buffer health is at risk, the player should generally prefer dropping to a lower sustainable representation over continuing to request a rendition that risks a stall — a brief, often unnoticed quality drop is a better outcome than a visible playback stall for most products.

Representation switches occur at segment/fragment boundaries defined by the packaging format, not at an arbitrary mid-segment point — but the exact mechanics of where a switch is legal vary by streaming technology, so this should be understood as a packaging-defined boundary rule rather than an absolute 'never mid-segment, ever, for every technology' claim.

1) Metadata/authorization request — resolving what the viewer is allowed to play. 2) Manifest fetch — retrieving the master and initial representation manifest. 3) Connection setup where applicable — DNS resolution, TLS handshake, connection establishment to the serving edge. 4) First segment fetch — downloading enough of the first segment to begin decode. 5) Decode and first-frame render.

Without it, a viral video creates independent cold misses at every single edge location worldwide, each one making its own trip to origin — origin sees N misses for effectively the same object. A shield/tiered layer collapses that fan-in: many edges' misses resolve against the shield, and only the shield's own (much smaller number of) misses reach origin. See Origin Protection and Failure & Scale -> CDN Cache-Miss Storm.

video/version + representation + segment is the conceptual shape of a segment's cache key; a real implementation typically also folds in content type/format as needed. Because segment objects are immutable once published (see Safe Output Publication), this key can safely carry a very long TTL — the bytes behind it will never change.

A manifest may need different TTL/versioning treatment than its segments — for VOD, once a specific version is finalized, that version's manifest can also be treated as immutable, but the active-version pointer the player resolves before fetching a manifest is what actually changes over time (on reprocess, or on a version rollback).

If a signed authorization token is carried as a query parameter and the CDN's cache-key configuration naively includes every query parameter, every viewer effectively gets a unique cache key for the same underlying object — destroying the hit ratio. Cache-key configuration needs to strip or normalize the authorization parameter out of the cache key itself while still enforcing it at the authorization layer, so caching stays efficient without leaking access to a different viewer. See Failure & Scale -> Cache-Key Fragmentation.

When multiple concurrent requests miss for the same object at the same cache tier, only one in-flight fetch to the next tier (or origin) should occur; the rest wait on that single fetch's result rather than each triggering their own.

A tiered caching layer between edges and origin specifically to collapse cross-edge miss fan-in — see CDN Cache Hierarchy.

Origin should enforce its own request-rate and concurrency limits regardless of what the CDN layer does, so a misconfiguration or an unusually large miss event can't overwhelm it.

Where appropriate, origin should only accept requests from the CDN/shield layer, not directly from arbitrary clients — removing an entire class of traffic that could otherwise bypass the caching hierarchy altogether.

If origin is genuinely overwhelmed, it's better to shed some requests deliberately (returning a clear, fast failure) than to degrade every request slowly and risk cascading timeouts upstream. See Failure & Scale -> Cascading Failure.

Authorization can be trivial or effectively a no-op — anyone can request playback metadata and receive a credential (or no credential is needed at all if the CDN/origin is intentionally open for public content).

It is not enough for the metadata API to check entitlement if the underlying CDN or object origin will serve the manifest/segments to anyone who guesses or replays a URL. The delivery layer itself needs to require and validate the short-lived credential — otherwise 'private' is enforced only at one checkpoint that can be bypassed.

Making a previously public video private requires, together: stop issuing new authorization for it, update its metadata/visibility state, remove it from search/discovery, and revoke or bound the validity of any previously-issued cached access according to the delivery design (a signed credential that's already short-lived limits how long this window can stay open). See Failure & Scale -> Metadata Cache Stale Privacy and Video Deleted, CDN Cached.

Has the original been durably uploaded? (uploaded) Are outputs currently being produced? (processing) Does a validated, playable artifact set exist? (ready) Does product policy currently permit discovery/playback? (published/visible) Is access currently restricted for another reason? (blocked/private/deleted). A suggested lifecycle shorthand is UPLOADING → PROCESSING → READY/PUBLISHED → BLOCKED/DELETED, but a real implementation can and often should separate 'is it technically ready' from 'is it currently visible,' since those can change independently (a ready video can be made private without reprocessing anything).

An ordinary title/tag edit can tolerate the platform's normal indexing lag. A deletion or a privacy change to more restrictive (public → private/blocked) is a different category of update — it should propagate with materially higher urgency, because the cost of a stale index entry here isn't 'slightly outdated search result,' it's 'search is showing content the owner no longer wants discoverable.' See Failure & Scale -> Search Index Stale Delete.

A stable event identity (for deduplication), the video ID, a playback/session identifier, an event timestamp, and whatever 'counted' threshold or policy version produced it (so later analysis knows which counting rule was in effect).

There is no universal technical definition. An illustrative policy might be 'emit a countable view after playback crosses the platform-defined watch threshold' — but the specific threshold, and whether it's a fixed duration, a percentage watched, or something else entirely, is a product decision this architecture should treat as configurable, not hard-code.

Aggregation workers de-duplicate by the event's stable identity within a bounded, retained dedupe window — this suppresses duplicates that arrive within that window (a very common and sufficient case for retried deliveries). It does not, by itself, guarantee a mathematically exact lifetime count: an event delayed longer than the retained window, or a true dedupe-state loss, can still be double-counted or missed. See Trade-offs & Decisions -> Exact vs. Approximate View Count and Failure & Scale -> View Event Duplicate / View Event Loss.

Local or partitioned partial aggregation (each of several parallel workers keeps its own partial sum for the hot key, merged periodically), keyed stream re-partitioning specifically for detected hot keys, sharded counters that get merged on read or on a schedule, or hierarchical aggregation (aggregate locally first, then aggregate the aggregates). The right choice depends on the stream-processing infrastructure already in place.

Oldest job age (how long has the longest-waiting job been waiting), queued media minutes (total source duration still waiting to be processed — a work-weighted measure), estimated compute work (factoring resolution/codec/duration, not just count), per-priority backlog (so a high-priority queue's health isn't hidden by a large low-priority backlog), and measured processing-completion SLO attainment (are jobs actually finishing within the target window, not just 'is the queue draining').

Scaling worker count purely off raw job count can under-provision when the backlog is dominated by a few very expensive jobs, or over-provision when it's dominated by many cheap ones. Feeding a work-weighted estimate (queued media minutes, or estimated compute work) into the autoscaling signal is a meaningfully better fit. See Trade-offs & Decisions -> Fixed vs. Elastic Workers.

Original source retention policy (keep indefinitely? for a bounded window? only until derived outputs are confirmed durable?). Derived renditions/segments/thumbnails (these are generally reproducible from the original if it's retained, which is itself a real trade-off — see Trade-offs & Decisions -> Precompute vs. On-Demand Renditions). Cold tiering for rarely-accessed content. Reprocessing artifacts from a superseded version. Orphan cleanup for failed processing attempts' staging objects. Deleted-content cleanup. Abandoned/expired multipart uploads that were never finalized.

Mark the video unavailable in authoritative metadata. Stop issuing new playback authorization for it immediately. Remove it from search/discovery. Purge or invalidate CDN-cached copies as the delivery design requires. Delete or expire derived artifacts (renditions/segments/manifests/thumbnails) according to retention policy. Delete the original according to policy (which may differ from derived-artifact policy). Handle retries for any step that fails. Audit that the workflow actually completed.

Stopping new authorization does not retroactively invalidate a credential a viewer already obtained before the deletion started, unless the delivery design includes active revocation — this is the same reasoning as Playback Authorization's privacy-change discussion, applied to the terminal case of deletion.

Globally unique video/upload IDs (so identifiers never collide across regions). Each creator's upload is assigned a home/ingest region. Authoritative metadata write ownership belongs to one region per video/partition at a time. Reads elsewhere are served from asynchronously replicated copies, accepting some replication lag for locality. Object replication follows a policy driven by durability requirements, data-residency constraints, popularity, and cost — not 'replicate everything everywhere.' Failover to a different authoritative writer happens only after an explicit ownership/fencing decision — never as an automatic reaction to a network partition alone.

Without a fencing step, a network partition could let both the original region and a newly-promoted region believe they're the authoritative writer for the same video/partition at the same time — producing genuinely conflicting metadata updates that are hard to reconcile after the fact. See Failure & Scale -> Region Partition Split-Brain.

A multipart upload session is generally tied to the region/storage session it was created against. A region failure mid-upload should not be assumed to seamlessly hand off to another region unless the upload architecture explicitly supports that — see Failure & Scale -> Regional Failure.

Upload success/failure rate, upload completion latency, abandoned-session rate, finalize failure rate.

Processing queue depth, oldest job age, queued media minutes, per-stage failure rate, processing time per source minute, output validation failure rate, publication latency.

CDN hit ratio, shield hit ratio, origin request rate and egress volume, segment 4xx/5xx rate, manifest error rate.

Startup time, rebuffer/stall ratio, playback error rate, delivered bitrate/quality distribution, and seek latency — these are more meaningful QoE signals than raw HTTP latency alone, since they reflect what a viewer actually experiences.

Search indexing lag, view-event processing lag, deletion propagation lag.