Design a video service (YouTube or Netflix)

01Functional requirements

A video service accepts uploads, lets viewers find videos and plays them on supported devices. A viewer’s download speed may fall when Wi-Fi weakens or mobile reception gets worse. If video data arrives too slowly, playback pauses after the player uses the video it has already downloaded.

The service prepares several video quality levels so the player can switch to one that needs fewer bits per second. It downloads short pieces, rather than the whole original file. Keep titles, access rules and saved playback positions in separate records because those small updates should not require rewriting video files.

1. FR1: Upload and prepare videos. Resume interrupted uploads and show processing progress. Prepare the required quality levels, playback playlists and thumbnail before publishing a playable video.

2. FR2: Share and play. Let viewers share a video reference, play, pause and seek on supported devices. When download speed drops or the player has little downloaded video left to play, switch to a lower quality that needs fewer bits per second.

3. FR3: Search the catalog. Find videos by title. Return only current metadata and thumbnails the viewer may see.

4. FR4: Record engagement. Define which accepted playback-start event counts as a view. Let each account choose like, dislike or neutral for each video. Display totals may update later.

5. FR5: Manage comments. Save comments without duplicating them on retries. Return permitted comments in pages ordered by video and time.

6. FR6: Resume playback. Save per-account progress with explicit rules for competing sessions and devices. Seeking backward is a valid update; the farthest position is not always the desired resume point.

7. FR7: Control private media. Check current permission or paid access before issuing temporary media credentials. Search and catalog results must follow the same visibility rules.

Out of scope

• Live broadcasting, advertising auctions and subscription billing.
• Recommendations and discovery products beyond title search.

Example: Mira uploads v81, “Building a raised bed.” Ben searches for it, watches session s9, comments and later resumes from his saved position.

02Nonfunctional requirements

Assume 100,000 ten-minute uploads per day, ten million 20-minute viewing sessions per day and 500,000 viewers at peak. Confirm the supported devices, network conditions and load under which the following targets apply.

1. NFR1: Playback startup. At least 95% of playback starts take no more than two seconds in the agreed test. A successful segment download alone does not measure time until playback starts.

2. NFR2: Playback continuity. Time spent stopped for rebuffering is below 1% of aggregate watched time in that test. Lower connection capacity needs lower quality; no service can guarantee uninterrupted playback on every connection.

3. NFR3: Playback availability. Authorization for ready videos meets 99.9% availability per calendar month. Optional counters and AI captions do not block playback.

4. NFR4: Durability and readiness. Saved originals and acknowledged comments survive one storage-node failure. A ready video references all required verified outputs. Accepting an upload and publishing a playable video are separate steps.

5. NFR5: Processing time. At planned load, at least 95% of valid ten-minute uploads finish required encoding within an assumed 30 minutes. Failed quality levels can retry. Do not publish an incomplete required set.

6. NFR6: Private access. Check current access before issuing media credentials scoped to the account, video and version. They expire within 60 seconds of issue. An old catalog result cannot grant fresh permission; already downloaded bytes cannot be recalled.

7. NFR7: Display and search delay. Target at most one minute of counter delay and 30 seconds for search and comment-list updates. Count the defined session-start event once; segment downloads, retries and bots do not by themselves prove separate human views.

8. NFR8: Progress conflicts. Use ordered updates within a session and a revision check across devices. Do not simply keep the maximum position, because that would discard a valid backward seek.

03Let bandwidth drive the architecture

1. Original uploads: at 8 megabits/second for 600 seconds, one ten-minute video is 8 × 600 ÷ 8 = 600 MB. At 100,000 uploads/day, originals add 60 TB/day before copies and retention. Divide by eight because a byte has eight bits.
2. Viewing traffic: at 3 megabits/second for 1,200 seconds, one session transfers 450 MB. Ten million sessions need 4.5 PB/day. At 500,000 simultaneous viewers, aggregate playback reaches 1.5 terabits/second.
3. Segment size: a player downloads short pieces called segments. Four seconds at 3 megabits/second is about 1.5 MB. Test that duration against startup delay, request count and quality-switch speed; four seconds is an example, not a universal rule.
4. Prepared output storage: three quality levels at 1, 2 and 4 megabits/second for 600 seconds produce (1+2+4) × 600 ÷ 8 = 525 MB. At 100,000/day, outputs add 52.5 TB. Together with originals, that is 112.5 TB/day before replicas, audio, thumbnails, packaging and temporary work.
5. Segment requests: a 1,200-second session with four-second segments makes about 300 requests. Ten million sessions make three billion/day, about 34,700/second on average. At 500,000 steady viewers, one request each four seconds means 125,000/second, before startup, seeks, retries and audio.
6. Permission renewal: credentials expire in 60 seconds. Renewing every 50 seconds gives retry margin; 500,000 viewers ÷ 50 = 10,000 renewal checks/second, before starts and retries. Check access here instead of querying metadata for each segment.

Decisions

• Size upload/encoding storage separately from delivery bandwidth and segment request rate.
• Use distributed delivery caches and test how much missing content the origin can refill.
• Keep the smaller catalog, progress and credential-renewal paths separate. More catalog replicas do not provide media bandwidth.

04API Design: Requests, Responses and Retries

Begin an upload as the signed-in owner. The request key identifies this upload attempt, so repeating it after a timeout returns the same upload:

POST /video-uploads
Idempotency-Key: tour-81

{"title":"Building a raised bed","byteLength": 600000000,"visibility":"public"}

{"videoId":"v81","uploadId":"u81","partUrls":["<scoped-part-url>"],"state":"uploading"}

Finish the upload

1. Send each part to its returned URL. These temporary URLs permit only the parts reserved for upload u81.
2. Complete u81. The service verifies the bytes and returns 202 Accepted with state processing.
3. Check GET /videos/v81 for progress. When the required outputs are complete, it returns publishedVersion.
4. The same request key and content return the original upload. Changed content returns 409 Conflict; size or quota failure returns 413; unsupported media returns 415.

Start playback

1. Ben’s player chooses request key watch-9 for one intended playback start and calls POST /videos/v81/playback-sessions with that key. The service checks readiness and current permission. In one database transaction, save the session, the watch-9 result and the pending accepted-start work. The key is known before sending; s9 is the resulting session ID.
2. Success returns {"sessionId":"s9","mediaVersion":1,"manifestPath":"/media/v81/1/master.m3u8","resumeSeconds":120,"progressRevision":3,"credentialExpiresInSeconds":60} plus a temporary credential. The credential permits delivery of this account’s allowed video version. Retrying watch-9 with the same request returns s9 instead of creating or counting another session. Changed request content under that key returns 409; retries still check current access, and an expired credential needs normal renewal.
3. If required outputs are still being prepared, return 409 with code video_not_ready. The client checks video state again later; this rejected request creates neither a successful session nor a counted start.
4. Return 403 when access is denied, 404 when the video is absent, or 410 when it has been removed.

Keep playback authorized

1. Before its credential expires, session s9 calls POST /playback-sessions/s9/credentials.
2. The service rechecks the account's access and returns a credential valid for at most 60 seconds for the same account, video and media version.
3. Retry a failed renewal only within the remaining playback deadline, with a limit on attempts. Renewal does not create another session-start record or view count.
4. Revocation blocks new credentials. A previously issued credential may remain usable until its expiry, so the design promises that stated delay rather than immediate revocation at the CDN.

Search and record user actions

• GET /videos/search?q=raised%20bed&cursor=... returns a page of permitted video details and thumbnail locations.
• POST /videos/v81/comments uses a request key and returns 201 with the saved commentId. Retrying that request returns the original comment. GET lists comments by video and time.
• PUT /videos/v81/reactions/me sets this account's choice to like, dislike or neutral. Repeating the choice does not add another vote.
• GET /me/progress/v81 returns the saved position and revision, for example {"positionSeconds":120,"revision":3}. The playback-start result also supplies that revision.
• PUT /me/progress/v81 carries sessionId, sessionSequence, positionSeconds and expectedRevision. The player increments sessionSequence for each intended update; expectedRevision is the saved progress revision it last read.
• First look for a saved result for this account/session/sequence. The same update returns its original result even if the progress revision has since advanced; changed contents under that identity return 409. For a genuinely new update, check that its sequence is newer for that session and expectedRevision still matches. Save the position, next revision and update result in one transaction. A competing device’s accepted update makes the old revision conflict instead of being silently overwritten.

05Data Model and Storage Access Patterns

A rendition is one encoded quality level, such as a lower-bitrate version for a slow connection. A manifest is a playlist describing available qualities or their segment locations. A segment is a short piece of media that the player downloads and buffers.

A thumbnail is a separately prepared image. Do not extract a frame from the full original every time someone opens the catalog.

06Build a complete asynchronous pipeline

Start with a catalog application, a metadata database, private object storage and a background encoding program. A rendition is one prepared quality level; a segment is a short piece downloaded by the player; a manifest is the playlist naming available qualities and segment locations.

Upload and save the work

1. Mira uploads video v81 through upload u81. Split the transfer into parts so a failed part can retry without restarting successful parts.
2. Verify actual size and checksum. Save a processing job in the database before reporting that preparation is pending.
3. An application callback alone is insufficient: a restart would forget it. A saved job lets another program resume.

Prepare and publish

1. An isolated worker inspects the original and produces required quality levels, segments, manifests and a thumbnail.
2. Identify tasks by video, version and profile so missing work can retry without repeating everything.
3. Verify the complete required output set. The catalog database marks version 1 ready only if the video’s current version, processing state and worker attempt still match. Save pending title-search work in that same transaction. A late worker cannot restore a deleted video or publish over a replacement task. Do not expose half-prepared playback.
4. Keep published objects unchanged. A later encoding gets a new version, rather than modifying segments a player already holds.

Serve the first product

• An HTTP origin serves prepared segments from storage. Indexed catalog and title-search queries find videos.
• Comments, reactions and saved playback position use separate small records.
• Encoding and segment downloads do not wait for optional counters. Later stages give encoding workers and media delivery independent capacity.

07Make asynchronous preparation recoverable

Recover one failed quality level

1. Job j81 requires low, medium and high qualities plus thumbnail t81. Medium finishes; the high-quality worker crashes.
2. Saved per-profile job rows show what is complete. Retry high under the same video/version/profile identity and verify medium for reuse.
3. Publish one ready version only when every required output passes validation. A repeated queue message must not publish again.

Close the save-to-queue gap

1. Save pending processing work with verified upload metadata. This pending-work record is an outbox entry.
2. A relay program reads it, sends the job to the queue and records progress. If its response is lost, it sends the same job again.
3. The worker checks saved job/output state before performing missing work. Each task records its current attempt ID and deadline. A replacement receives a new attempt ID; finishing an old attempt cannot mark the replacement complete. Publishing checks the current video version/state and required tasks in the same transaction. The queue remembers unfinished work, but these database checks prevent a repeated or delayed worker from publishing twice or restoring deleted media.

Give other updates their own rules

• Reactions: keep one choice per account/video. For each identified change, the counting program checks its processed-change table. If absent, save that ID and update the displayed total in one transaction; a repeated ID leaves the total unchanged. Saved choices allow a later rebuild.
• Views: save one accepted-start row under the unique pair (sessionId,start). Add it and its count change together only if absent. A retry finds the row and adds nothing. Segment downloads are not new starts.
• Progress: the player reads the current revision, numbers each intended update and retries a lost response with that same number and content. In the transaction, first return an already saved result for that account/session/number. Otherwise reject an older session number, check current permission and expected revision, then save the position, increased revision and retry result together. If another device changed revision 3 to 4, a new update expecting 3 conflicts; repeating an already accepted update returns its own result. A later valid seek 120→90 still saves 90; the position itself need not increase.

Sending these operations through a queue does not decide their meaning or automatically make external effects happen exactly once.

08Deliver segments through an edge network

Distribute expensive work

1. Add memory/CPU while one machine remains sufficient. Then add independent catalog instances and encoding workers.
2. Serve unchanged media segments through a content delivery network. Missing segments fetch from a controlled origin.
3. For a sudden popular segment, share a refill among simultaneous requests or use an intermediate origin cache. Otherwise cache misses can overwhelm the origin together.

Keep playback going when download speed falls

1. The player reads the playlist listing available quality levels and chooses one its device can decode.
2. As it downloads each segment, it measures how quickly bytes arrive and how many seconds of downloaded video remain. This saved video waiting to play is the playback buffer.
3. A quality that needs 3 megabits/second cannot keep playing indefinitely over a connection delivering 1 megabit/second. Before the buffer empties, choose a lower prepared quality that fits the measured download speed, leaving room for further drops.
4. Prepare matching segment times and decoding start points across quality levels. The player can then request the next segment at a lower quality without skipping or replaying part of the video.
5. Shorter segments can make quality changes happen sooner, but require more requests. Test startup time, switching, request count and cache reuse. Adding catalog servers does not improve the viewer’s Wi-Fi or mobile download speed.

Scale the small records separately

• Hash videoId to distribute video rows; retain owner/time and title-search indexes for those different queries.
• One popular video can receive many comments at once. Cap comments per response and index them by video and time; divide long histories into time ranges. Process view totals in batches only if the product accepts a delay before those totals change.
• A public title may briefly be old on a replica. Confirm the owner’s publication using a database read that includes the committed update. Check current account, audience and subscription records before issuing private or paid-media credentials; an old public title copy cannot grant access.
• Cache metadata, thumbnails and segments separately because their sizes and access rules differ.

Renew private access

1. Before its 60-second media credential expires, the player asks the access service to check permission again.
2. If renewal is denied, stop fetching protected bytes after the old credential expires.
3. Already downloaded/buffered bytes cannot be recalled. An old public catalog response cannot issue new permission.

09Metadata, thumbnails and duplicate content

Share bytes without merging videos

1. Repeated playback of v81 can reuse cached version 1 segments.
2. A different creator uploading identical bytes still gets a separate video record, title, audience and comments.
3. A verified content hash may permit shared storage among files belonging to the same owner or an explicitly shared library, after checking access. Keep references and lifetimes separate; do not reveal another person's private upload through an existence response.

Keep catalog records small

• Prepare thumbnails as objects keyed by video/version/size. Store their locations in metadata; serve image bytes through delivery caches.
• Owner-based partitions make one owner's listing local but can overload large creators. VideoId hashing spreads rows and needs a separate owner index.
• Time ranges concentrate new uploads unless further divided.

Calculate each cost

1. An 8 megabit/second original lasting 600 seconds is 600 MB: 60 TB/day for 100,000 uploads.
2. A 1,200-second view at 3 megabits/second is 450 MB: 4.5 PB/day for ten million sessions.
3. One hundred million 50 KB thumbnail displays add 5 TB/day.
4. One million 1 KB metadata rows need 1 GB of raw cache memory.

These distinct workloads justify separate caches and indexes. A segment download should not need a new catalog database query every time.

10Trace upload and playback separately

1. Finish the upload: verify Mira's bytes under u81 and save processing job j81 for video v81. These labels identify one upload, its work and the video, respectively.
2. Publish: workers verify all required segments, playlists and thumbnail t81. Mark media version 1 ready and save work to update title search.
3. Discover: Ben searches “raised bed.” Search finds v81 as a possible match; the application loads current catalog details and checks permission before showing title or thumbnail.
4. Start playback: Ben sends request watch-9. A permitted request saves its result, session s9 and pending start work together, then returns temporary credentials and the saved progress revision for version 1. If the reply is lost, watch-9 recovers s9. His player reads the playlist and fetches segments from delivery caches.
5. Count the product action: process (s9,start) once, even when retried. Store one Ben/video reaction for repeated like requests and one comment for a repeated comment request key.
6. Save progress: Ben reads saved progress revision 3. His session’s update 12 records 120 seconds and advances it to 4. Repeating update 12 returns that saved result. His next update, 13, can save 90 seconds after a backward seek if revision 4 is still current. Keeping only the maximum would erase his intent; another device’s intervening update instead causes a revision conflict.
7. Delete: save a newer deleted-state marker, stop new media credentials, filter search/comment access and schedule media cleanup. Existing credentials retain only their short stated lifetime.

Renew the 60-second media credential after 50 seconds to leave time for a retry. Save playback position after a pause or seek, and periodically during playback—for example, every ten seconds while the network is working. That example may lose up to ten seconds of progress after a crash; failed saves require retrying the same numbered update. Do not query catalog metadata for every segment or make playback wait for optional counter updates.

11Discuss failure, observability and cost

1. Encoding backlog: keep existing ready videos playable, limit incoming upload work/retries and expose processing delay or failure honestly. After a task exhausts its retries, move it to a separate inspection queue with its video, version, quality and error. Operators can repair the cause before retrying; this is often called a dead-letter queue.
2. Origin failure: cached segments may still work. Missing ones need a redundant origin or an explicit playback error. An unrestricted bucket URL would bypass access checks and is not a safe fallback.
3. Stale catalog: an old title does not grant permission. Check current visibility before returning protected text, thumbnails or new media credentials.
4. Untrusted content: isolate parsers, validate media duration/type/size, enforce quotas and escape comment text. Retain only needed playback data.
5. Measure experience: startup time, pauses while waiting for more video, delivered quality and segment errors show whether playback targets hold.
6. Measure work and cost: track origin requests, processing age, counter delays and progress conflicts. Delivery, encoding, extra qualities and retained originals have separate costs.