Design a photo-sharing service (Instagram)

01Functional requirements

The product stores photos and shows posts from followed authors. The original is the uploaded image; display variants are smaller prepared copies for different screens.

1. FR1: Upload and manage photos. Let an author upload an original photo, check processing progress, publish it and remove it. Prepare the required display sizes before publishing; viewers must not receive a half-prepared photo.

2. FR2: View and download. Check the viewer’s permission, then return photo details and a prepared image large enough for the requested display dimensions. Avoid sending the full original for a small feed preview. Support public photos and photos restricted to an approved audience.

3. FR3: Search titles. Find published photos by title. Check current visibility before returning a title, snippet or image reference.

4. FR4: Follow accounts. Support following, unfollowing and approval for private accounts. Removing approval must remove access even if an old feed entry still mentions the photo.

5. FR5: Generate home feeds. Show posts from followed authors, with pages that do not shuffle unpredictably while the viewer moves through them. Begin with newest-first ordering and use it if optional ranking fails.

Out of scope

• Video, photo tags or tag search, user tagging and comments.
• Suggestions about whom to follow and posts from outside the follow graph.

Example: Mira uploads p81, “Garden opening.” Ben follows her, searches its title and sees it in his home feed.

02Nonfunctional requirements

Assume ten million daily active users. Five percent upload two photos each day; each user views 100 photos. These are planning assumptions to confirm and test.

1. NFR1: Feed latency. At least 95% of primary-region feed requests finish within 300 ms at the planned peak. Downloading images is measured separately.

2. NFR2: Feed availability. Feed requests meet 99.9% availability per calendar month. If optional ranking fails, return posts ordered by creation time, newest first.

3. NFR3: Media durability. Published originals and required display sizes survive one storage-node failure under the selected storage service's guarantees. Unfinished temporary uploads are excluded; this is not a promise that data can never be lost.

4. NFR4: Publication readiness. Verify every required image before publishing its reference. At normal load, at least 95% of valid uploads publish within 30 seconds. Show failures and allow retries.

5. NFR5: Audience revocation. Check current approval before issuing private-image download credentials. Previously issued credentials expire within 60 seconds. Already downloaded images cannot be recalled.

6. NFR6: Search, feed and pagination behavior. A photo may become searchable or appear in feeds shortly after publication rather than instantly. For ranked pages, save the ordered post IDs and continue from the last returned position; use post ID to order equal scores. Unrelated photos do not need one globally agreed creation order.

7. NFR7: Isolate expensive work. Limit simultaneous image validation, resizing, feed updates and retries separately. A slow transform or an author with millions of followers must not consume every resource needed to serve feeds.

03Calculate the media budget

1. Uploads: 5% of ten million users = 500,000 uploaders. Two photos each gives one million/day, about 12 uploads/second on average.
2. Stored images: one million × 4 MB originals = 4 TB/day. Display variants adding 30% bring the total to 5.2 TB before replicas and backups.
3. Displayed bytes: ten million viewers × 100 photos = one billion image displays/day, about 11,600/second. At 50 KB per display, transfer 50 TB/day. Serving smaller prepared sizes and nearby cached copies matters far more than enlarging caption rows.
4. Follower updates: a post by an author with ten million followers may need ten million home-list insertions. Measure active followers and posting rates; average upload rate cannot size that burst.

Decisions: store originals durably, prepare copies for the display dimensions the application supports and deliver repeated images through a content delivery network. Put follower-list work in limited background workers, and compare prepared lists with merging large-author posts when viewers read.

04API Design: Requests, Responses and Retries

Reserve bytes separately from publication:

POST /uploads
Idempotency-Key: upload-81

{"mediaType":"image/jpeg","byteLength":4000000}

{"uploadId":"u81","putUrl":"<scoped-url>","expiresInSeconds":900}

Publish the uploaded photo

1. Send the image to the upload URL within 900 seconds. The URL permits only this reserved upload.
2. Call POST /posts with request key publish-81 and {"uploadId":"u81","title":"Garden opening","caption":"Come Saturday","visibility":"followers"}.
3. The service returns 202 Accepted and {"postId":"p81","state":"processing"} while it prepares the required display sizes.
4. Check GET /posts/p81. When all required images are ready, it reports published state and their versioned locations.

Retries and errors

• The same key and content return the same post ID; the retry does not publish a second post.
• Changed content under that key returns 409 Conflict.
• An oversized upload returns 413; an unsupported media type returns 415.
• Reading a private post without permission returns 403. Reading a deleted post returns 410.

Browse and change access

• GET /authors/M/posts?cursor=... lists Mira's posts; M is her account ID.
• GET /home?cursor=... lists a home-feed page, for example {"items":[{"postId":"p81","mediaVersion":1}],"cursor":"<ranking-view-cursor>"}.
• GET /photos/search?q=garden&cursor=... searches titles. Each cursor identifies where the next page continues.
• Ben calls PUT /authors/M/follow to follow Mira and DELETE /authors/M/follow to unfollow. A private account records the follow as pending until Mira approves it.
• Mira calls PUT /followers/Ben/approval to approve Ben or DELETE /followers/Ben/approval to revoke approval. The handler checks that the signed-in account owns the private account before changing that relationship. Repeating either operation leaves the same final relationship state.
• Mira calls DELETE /posts/p81. The handler checks ownership and saves the deleted state before returning success; repeating deletion succeeds without creating another operation. Supplying another ownerId cannot grant permission.

05Data Model and Storage Access Patterns

A published post is the original record. Search hits and feed entries are copies used to find posts; they do not independently decide whether a viewer may see one.

The author index begins with authorId because the query asks for one author's posts. A globally unique postId alone cannot efficiently answer that query.

06Complete upload before optimizing feeds

Start with an application, a database for post details and private object storage for image bytes. A variant is a prepared size of the photo, such as a thumbnail or display image.

Upload and publish

1. Mira requests upload u81 and sends the original image. u81 identifies this upload; publish-81 identifies her later request to create a post from it.
2. The application checks actual length, type and checksum. An image-processing worker decodes it outside the feed-serving process, with memory and time limits for malformed files. For this example, remove embedded GPS coordinates from display copies, then create the required image sizes.
3. Save each processing task under its post, version and task name. After a crash, another worker checks completed outputs and retries only missing work. Do not rely on an in-memory callback.
4. After verifying every required output, the worker asks the database to publish p81 only if its saved post version, processing state and task attempt still match. In that same transaction, save the feed/search work to deliver. A delayed worker cannot republish a post that Mira deleted or a newer task replaced. Readers cannot see a partially prepared photo.
5. Clean abandoned uploads only after their deadline and grace period, while protecting active tasks.

Serve the first feed and search

1. Ben follows Mira. The feed handler reads recent posts from followed authors, removes posts Ben may not see and merges the rest newest first.
2. The response names a prepared image that meets the requested display dimensions, rather than always sending the large original.
3. Title search can initially use a database text index. Before showing a title, snippet or image, check that the original post is still published and permitted.

At small load, the application may receive upload bytes itself. Later let clients upload directly through restricted storage URLs and run image processors separately. Reserving, verifying and publishing remain distinct steps.

07Evolve media delivery and feed generation

Deliver image bytes efficiently

1. Prepare the sizes needed for thumbnails, small screens and large screens. Serve these through a content delivery network, which keeps reusable copies near viewers.
2. Unchanged public images can have long cache lifetimes, with a stated deletion/purge policy.
3. Private downloads require a fresh permission gate or temporary credentials within the revocation limit. A stale feed entry is not permission to download.

Prepare feeds for ordinary authors

1. After publication, a relay reads the saved feed-update record and passes it to a background program that finds Mira’s active followers. If the relay crashes before saving its delivery confirmation, it may send the same update again.
2. It inserts p81 into each follower's recent home list. Use a unique (viewerId,postId) pair so retrying an insertion cannot add the post twice.
3. Ben's next request reads that prepared list, loads current post details and checks permission before returning images.
4. This is fan-out-on-write: one publication triggers many background feed writes, reducing later read work. Keep only a limited recent window, grouped by viewer.

Handle very large audiences differently

1. One author with ten million followers can require ten million feed insertions for one photo.
2. Keep that author's recent posts in an author index instead. When Ben requests his feed, merge a limited number of those posts into his prepared list.
3. The hybrid combines prepared lists for ordinary authors with read-time merging for large audiences. Estimate feed insertions/second as the author’s posting rate × active followers. Use read-time merging when those insertions would exceed the workers’ tested capacity or make posts appear later than the feed’s freshness target; include the added author reads in the comparison.

08Choose IDs and metadata partitions

Choose capacity before partitioning

• Add database memory if that solves the current limit. Replicas can serve public metadata when a short delay is acceptable.
• Mira's immediate “published” confirmation must read a copy known to include her saved publication.
• Scale request handlers separately from image workers so resizing does not consume all feed-serving resources.

Retrieve records after finding IDs

1. Mira's posts p81 and p82 may live on partitions 2 and 7. An author/time index lists their IDs in order.
2. The feed handler groups those IDs by partition and fetches their current titles, visibility and image references in batches. This is sometimes called hydration: loading the details behind an ID.
3. Map logical partitions to machines so selected groups can move during growth. A modulo directly tied to machine count can move many records on every resize.

Choose IDs separately from storage placement

• A database sequence issues distinct integers; assigned ranges can reduce calls to the issuer.
• Random IDs need duplicate handling and do not imply creation order.
• Time/worker/sequence IDs and UUIDv7 carry time information. For a time/worker/sequence generator, assign each worker a distinct worker ID, wait when its sequence for one clock tick is full, and stop or wait if its clock moves backward. These rules prevent reusing an earlier combination. Such IDs still do not establish one agreed publication order across all authors; use the index required by the listing query.

09Rank feeds and search without confusing their indexes

Rank eligible posts

1. Ben follows Mira and Lee. Their posts p81 and p90 are candidates: possible feed results, subject to current permission.
2. Start newest first. A later rule may combine age with Ben's prior interactions, so the slightly older p90 can rank above p81.
3. Save the ordered post IDs for this browsing session, using post ID to order equal scores. The page cursor identifies that saved list and the last returned position. Later pages continue the same order instead of changing when new scores arrive.

Search titles separately

1. A title index maps words such as garden to post IDs. This word-to-ID structure is an inverted index.
2. Load the current post behind each matching ID and check permission before returning its title, snippet or media. An old index may still contain a deleted or newly private post.

Budget each cache for its own work

• One million 4 MB originals/day add 4 TB; display images adding 30% need another 1.2 TB.
• One billion 50 KB displays/day transfer 50 TB. Metadata caching cannot provide that media bandwidth.
• One million 1 KB metadata rows need 1 GB before overhead; 100,000 50 KB images need 5 GB. Measure repeated use separately for records and images.

Why stage 3 separates feed workers

1. The source database stores posts and follow relationships. A separate home index holds prepared candidate IDs for each viewer.
2. Feed workers save progress and use unique recipient/post insertions, allowing a crash to resume without duplicates.
3. Reads combine prepared IDs with large-author IDs, load current records, check visibility and rank a limited set. These extra recovery and merging rules are the cost of reducing repeated author queries.

10Follow a photo to a viewer

1. Upload: Mira sends her original under upload u81. Workers verify it and create all required display sizes.
2. Publish: check the current processing version and task attempt, then save p81 as published with version 1 and its pending feed/search update in one database transaction. Both records survive an application crash; a late worker cannot restore a deleted post.
3. Index the title: a background program adds “Garden opening” to title search. Search still checks the current post and audience before showing a result.
4. Prepare Ben's feed: insert (Ben,p81) only if that pair is absent. A repeated publication event cannot create another entry.
5. Read the feed: combine Ben's prepared list with recent posts from exceptional large authors, fetch current details and check permission. Return the page with a cursor naming its saved post order and last returned position.
6. Download: Ben fetches a prepared image large enough for his display dimensions through the delivery network. A small feed preview need not download the 4 MB original.
7. Delete or revoke: Mira removes p81 or Ben's approval. Stop issuing new private-media credentials immediately according to the stated permission check. Previously issued private-image credentials expire within 60 seconds. A cached image must still require a valid credential; deleting a feed/search entry alone does not block its download. An image already downloaded to Ben’s device cannot be recalled.

Keep delays explicit

• Publication can finish before title search catches up.
• An old feed can still contain a deleted post's ID, so the read must check current state.
• Previously issued download credentials may work until expiry; already downloaded bytes cannot be recalled.

11Explain operation, abuse and trade-offs

1. A required image fails: leave the post processing or failed, save which output is missing and retry within a limit. Do not publish broken required images.
2. The prepared feed fails: a limited author-query merge can fall back, but cap source queries. Hundreds of new database reads per failed feed request could spread the outage.
3. Deletion cleanup lags: save current deleted/private state first and block fresh credentials. Remove old feed/search entries in the background while filtering them during reads.
4. Cleanup races processing: keep any object needed by active image tasks or retained versions. An unfinished upload is not automatically abandoned.
5. Abuse: verify actual media type, enforce quotas, handle embedded location data deliberately and limit rapid follow changes.
6. Measure: track request latency, publication time, queued feed-update age, permission denials, cache reuse and bytes delivered. Compare image-processing cost with repeated downloads, and prepared-feed writes with repeated author reads.