Design a Photo Sharing App (Instagram style)

A frontend system design walkthrough for a photo first app. You will learn to serve the right image size to every screen and to prepare and upload photos on the client. You will also lay out grids that never jump and stay inside phone memory limits.

Frontend system design · Classic design question

After this page you can design the web client for a photo sharing product. You can explain responsive images, image CDN transforms, a worker based upload pipeline, grid and lightbox rendering, stories, and image memory on mobile.

Correctness contract: every image box has its final size before the image loads. An upload the user started is never silently lost, and it never posts twice. The app never loads more decoded image memory than the device can hold.

Assumptions: a mobile first web app or PWA. An image CDN can resize and change format on the fly. An object store accepts chunked uploads. Most users are on phones, many on mid range Android devices.

In a photo app, images are the product. They are also the biggest cost in bytes, in decode time, and in memory. A single phone photo can be 12 megapixels and 5 MB. Shown at full size on a 400 pixel wide screen, it wastes 95 percent of its bytes and about 48 MB of decoded memory. The client must ask for the right size, show something useful before the bytes arrive, and release memory when images leave the screen. Uploads have the opposite problem. The client holds a huge original file on a weak network, and it must shrink it, fix its orientation, and send it reliably. This page covers both paths.

Contents

  1. Concepts to understand first
  2. 1. Clarifying questions and requirements
  3. 2. Scope and budgets
  4. 3. High-level architecture
  5. 4. Data model
  6. 5. Interface and API
  7. 6. Deep dive: responsive images and the image CDN
  8. 7. Deep dive: the client upload pipeline
  9. 8. Deep dive: grid and masonry without layout shift
  10. 9. Deep dive: lightbox, carousel, and stories
  11. 10. Deep dive: placeholders and prefetching
  12. 11. Deep dive: memory limits on mobile
  13. 12. Failure modes
  14. 13. Trade-offs
  15. 14. 45-minute interview walkthrough
  16. 15. Summary
  17. 16. Common mistakes
  18. Worked example: posting one photo
  19. Code lab: a justified row layout
  20. Check yourself
  21. Key terms
  22. Further reading

Concepts to understand first

srcset and sizes

srcset lists the same image at several widths. sizes tells the browser how wide the image will be on screen. The browser combines this with the device pixel ratio and picks the smallest file that is sharp enough.

Example. A grid tile is one third of a 390 pixel screen at 3x density. It needs about 390 real pixels, so the browser picks the 400w file, not the 1080w file.

Limit. The browser chooses before layout. If sizes is wrong, it picks the wrong file. Browsers may also keep a larger cached file instead of fetching a smaller one.

Image CDN transforms

An image CDN resizes, crops, compresses, and changes format based on URL parameters or request headers. The client asks for exactly the size it needs. The CDN creates that variant once and caches it at the edge.

Example. /p/abc.jpg?w=640&q=75&fm=auto returns a 640 pixel AVIF to Chrome and a JPEG to an old browser.

Limit. Every unique width is a new cache entry. Allow only a fixed list of widths, or cache hit rate drops and cost goes up.

EXIF orientation

Cameras store the pixels in sensor order and add an EXIF tag that says how to rotate them. A photo taken in portrait may be stored landscape with "rotate 90 degrees" in the metadata.

Example. A user uploads a portrait photo. A naive canvas resize ignores the tag, and the posted photo is sideways.

Limit. Modern browsers apply EXIF orientation to <img> and to createImageBitmap by default. Old code that also rotates manually ends up rotating twice.

Layout shift

Layout shift happens when visible content moves because something above it changed size. Images without reserved space are the most common cause. Google measures it as Cumulative Layout Shift (CLS). A good score is under 0.1.

Example. A user is about to tap "Like". The image above loads and grows from 0 to 500 pixels tall. The user taps the wrong post.

Limit. CLS ignores shifts within 500 ms of a user input. That does not make those shifts pleasant.

Placeholders (LQIP and blurhash)

A placeholder shows the shape and color of an image before it loads. LQIP is a tiny, blurry version of the image, often under 1 KB. Blurhash encodes the blur into a short string of about 20 to 30 characters that the client decodes into pixels.

Example. The server sends blurhash: "LEHV6nWB2yk8pyo0adR*.7kCMdnj". The client paints a soft color blob in the image box at once.

Limit. Decoding blurhash costs CPU. Decoding 30 on the main thread at once can cause jank. Decode at a small size, such as 32 by 32, and scale up with CSS.

Decoded image memory

A compressed file is small. To draw it, the browser decodes it into a bitmap of width times height times 4 bytes. This bitmap is what fills memory, not the file size.

Example. A 150 KB JPEG at 1080 by 1350 pixels decodes to about 5.8 MB. Twenty of them is about 117 MB.

Limit. Browsers discard decoded bitmaps for off screen images on their own schedule. You cannot control this directly, only by removing or shrinking images.

1. Clarifying questions and requirements

Functional requirements

Non-functional requirements

Interview

Ask which path to focus on: viewing or uploading. Many interviewers want both at a high level and one in depth. Viewing is about bytes and layout. Uploading is about workers, reliability, and progress.

2. Scope and budgets

Device and screen

Bytes per image

Decoded memory

Frame budget

A frame is 16.7 ms at 60 Hz. Decoding a 1080 pixel JPEG can take 10 to 30 ms on a slow phone. If decoding happens on the main thread during a swipe, frames drop. Use decoding="async" on images, or call img.decode() before showing the next carousel slide. Never decode a 12 megapixel upload on the main thread.

DOM and bundle

3. High-level architecture

The app has two main paths that share a photo store.

Viewing path

Viewing path: the grid reads photo metadata from the store and observes tiles. Images load from an image CDN through srcset. The CDN transforms the original on a miss. Tapping opens a lightbox. The prefetch scheduler warms the next images through a Service Worker that stores them in Cache Storage. Stories preload the next story.
Figure 1. Viewing path. Metadata first, then the right size from the CDN, with prefetch for what comes next.

Upload path

Upload pipeline: the picked file goes to a Web Worker that fixes EXIF orientation and returns a preview. After editing, the worker crops, resizes, and encodes a 2048 pixel image, saved to IndexedDB. The upload queue creates a session, sends chunks with Content-Range, tracks progress, and finalizes with the caption. The server builds variants. Interrupted uploads resume from the last offset.
Figure 2. Upload pipeline. Heavy work happens in a worker. IndexedDB makes the upload survive reloads.

4. Data model

interface Photo {
  id: string
  width: number                // original pixel size after orientation
  height: number
  blurhash: string             // or lqipDataUrl
  dominantColor: string        // "#a38f7c", fallback background
  baseUrl: string              // CDN path, widths added by the client
  alt: string                  // user text or generated description
}

interface Post {
  id: string
  authorId: string
  photoIds: string[]           // 1 for single, up to 10 for carousel
  caption: string
  likeCount: number
  likedByMe: boolean
  createdAt: string
}

interface Story {
  id: string
  authorId: string
  photoId: string
  durationMs: number           // usually 5000 for a photo
  expiresAt: string
  seen: boolean
}

type UploadStatus = "processing" | "queued" | "uploading" | "paused" | "finalizing" | "done" | "failed"

interface UploadJob {
  jobId: string                // client id, used as idempotency key
  sessionUrl?: string          // from the server, for resume
  blobKey: string              // IndexedDB key of the processed file
  size: number
  uploadedBytes: number        // confirmed by the server
  status: UploadStatus
  caption: string
  attempt: number
}

interface Store {
  photos: Record<string, Photo>
  posts: Record<string, Post>
  stories: Record<string, Story[]>     // by author
  grids: Record<string, { ids: string[]; cursor: string | null }>
  uploads: Record<string, UploadJob>
}

The most important fields are width and height. They must be the size after EXIF orientation. With them, the client can reserve the exact box for every image before any byte arrives. The baseUrl lets the client build CDN URLs for any allowed width. The server does not need to send a long list of variant URLs.

5. Interface and API

Server API

GET  /api/feed?after=<cursor>                 -> posts + photos (side loaded)
GET  /api/users/:id/posts?after=<cursor>      -> grid page
GET  /api/stories/tray                       -> authors with unseen stories

POST /api/uploads   { jobId, size, mime }     -> { uploadId, sessionUrl, chunkSize }
PUT  <sessionUrl>   Content-Range: bytes 0-1048575/4200000   (chunk body)
     -> 308 Range: bytes=0-1048575   (more expected) | 201 { photoId }
HEAD <sessionUrl>   -> Upload-Offset or Range header, to resume
POST /api/posts     { jobId, photoIds, caption }   Idempotency-Key: <jobId>

This follows the shape of common resumable upload protocols, such as the one used by Google Cloud Storage and the open tus protocol. The client asks where to continue, then sends the rest. The jobId doubles as an idempotency key. If the network drops right after "create post", a retry does not post the photo twice.

Image URLs

https://img.example.com/p/abc123?w=640&q=75&fm=auto
allowed widths: 160, 320, 480, 640, 828, 1080, 1440

Set Cache-Control: public, max-age=31536000, immutable on image responses. A photo id never changes its pixels. An edited photo gets a new id or version. Use Vary: Accept if the CDN picks the format from the Accept header, or use separate URLs per format.

Component props

<ResponsiveImage photo={photo} sizes="(max-width: 600px) 33vw, 200px" priority={false} />
<PhotoGrid gridKey="profile:u_7" columns={3} gap={2} />
<Lightbox postId="p_1" startIndex={0} onClose={close} />
<StoryViewer authorIds={[...]} startAuthor="u_7" />

6. Deep dive: responsive images and the image CDN

The markup

<img
  src="https://img.example.com/p/abc?w=640"
  srcset="https://img.example.com/p/abc?w=320 320w,
          https://img.example.com/p/abc?w=640 640w,
          https://img.example.com/p/abc?w=1080 1080w"
  sizes="(max-width: 600px) 100vw, 600px"
  width="1080" height="1350"
  alt="Sunset over the harbor with two sailboats"
  loading="lazy" decoding="async">

Choosing widths

Each extra width adds a CDN cache entry per photo. Too few widths waste bytes. Seven widths between 160 and 1440 pixels keep the waste under about 20 percent for any screen. Round requested widths up to the nearest allowed width on the client. Never request w=413.

Device pixel ratio caps

A 3x phone does not need a true 3x image for a photo. Most people cannot tell 2x from 3x in a photo, but 3x costs about 2.25 times the pixels. Cap at 2x for photos. This saves a lot of data with no visible loss. Keep text and icons sharp with SVG.

Data saver

When navigator.connection.saveData is true, or the network is slow, choose a lower quality such as q=50 and cap at 1x. Some CDNs read the Save-Data request header and do this for you.

Tip

Say the numbers: a 390 pixel wide phone at a 2x cap needs about 800 pixels. Serving a 4000 pixel original wastes about 25 times the pixels. This is the most important optimization in a photo app.

7. Deep dive: the client upload pipeline

Why process on the client

A phone photo is 3 to 6 MB. On a 2 Mbps uplink that is 12 to 24 seconds. Resizing to 2,048 pixels and encoding at quality 85 brings it to about 400 to 700 KB. That uploads in 2 to 3 seconds. The server still makes its own variants. The client resize only saves upload time and server bandwidth.

The steps

  1. Pick. <input type="file" accept="image/*" multiple>. On mobile, the capture attribute can open the camera directly.
  2. Decode in a worker. Send the File to a Web Worker. Call createImageBitmap(file, { imageOrientation: "from-image" }). This decodes off the main thread and applies EXIF orientation.
  3. Preview. Make a small bitmap, about 1,080 pixels, for the edit screen. Transfer it back to the main thread as a transferable object, so it is moved, not copied.
  4. Edit. The user crops and picks a filter. Record the crop rectangle and filter as parameters, not as pixels.
  5. Render the final image. In the worker, draw the original onto an OffscreenCanvas with the crop applied, at a maximum of 2,048 pixels on the long edge. Apply the filter with canvas filters or WebGL.
  6. Encode. Call canvas.convertToBlob({ type: "image/jpeg", quality: 0.85 }). Use WebP if the server accepts it. Encoding strips EXIF, which also removes GPS location. That is good for privacy, but tell the user if you keep or drop location.
  7. Store. Save the processed Blob in IndexedDB with the job record. Close the bitmaps with bitmap.close() to free memory at once.
  8. Upload. Create a session, then send chunks.

HEIC files from iPhones need care. Safari can decode HEIC. Chrome on desktop often cannot. One option is to let iOS convert at pick time. It often does this when accept asks for JPEG. Another option is to upload the original and let the server convert. Always have a fallback when createImageBitmap fails.

Resumable chunked upload

Progress

Use XMLHttpRequest and xhr.upload.onprogress for byte level progress within a chunk. Fetch upload progress is not widely available. Show overall progress as confirmed bytes plus in flight bytes, divided by total. Split the bar: processing 10 percent, upload 85 percent, finalize 5 percent. A bar that sits at 100 percent while the server finalizes feels broken.

Let the user move on

After the user taps "Share", show the post at the top of their feed at once with a small progress ring. The upload continues in the background while they browse. On page close, warn only if an upload is still in progress. Background Sync in a Service Worker can retry later on browsers that support it, but do not depend on it everywhere.

Mistake

Resizing on the main thread with a regular canvas. A 12 megapixel decode and draw can block the main thread for 300 to 800 ms on a phone. The page freezes, and the progress bar cannot even animate.

8. Deep dive: grid and masonry without layout shift

Square grid

The profile grid uses square tiles cropped from the center. Use CSS Grid with grid-template-columns: repeat(3, 1fr) and aspect-ratio: 1 on each tile with object-fit: cover. Every tile has its size before load. CLS is zero.

Justified rows

The Flickr style layout keeps each photo's real aspect ratio. Photos are packed into rows of equal height that exactly fill the width. Algorithm: add photos to a row until the row, at a target height, would be wider than the container. Then scale the row height so the widths sum to exactly the container width. The code lab below implements this. Because the client knows every aspect ratio from metadata, it computes the whole layout before any image loads.

Masonry

Masonry places items in columns of equal width and variable height, like Pinterest. Place each new item in the shortest column. Compute positions in JavaScript from known aspect ratios, and use absolute positioning or CSS transforms. CSS has an experimental native masonry layout, but support is not universal yet. Do not depend on it.

Windowing a grid

Window by rows, not by items. A 3 column grid with 2,000 posts has about 667 rows. With rows of 130 pixels, render the 6 to 8 visible rows plus 3 rows of overscan each side. Use IntersectionObserver on a sentinel to load the next page of posts. Images in unmounted rows are released, which keeps memory bounded.

Intuition

A grid is a parking lot with painted spaces. Paint every space before the cars arrive, using the size you already know. Then no car pushes another out of its space when it parks.

Lightbox

Carousel

Stories

10. Deep dive: placeholders and prefetching

Placeholder ladder

  1. Dominant color. Free. A background-color on the image box from metadata.
  2. Blurhash or LQIP. Sent with the metadata. Decode to a 32 by 32 canvas, ideally in a worker, and show it scaled up with CSS. Or use a pre made tiny image as a data URL, about 200 to 600 bytes.
  3. Grid size image. When opening a detail view, reuse the already cached tile as the placeholder.
  4. Full image. Fade it in over 150 to 200 ms after decode. Skip the fade if prefers-reduced-motion is set.

Keep placeholder data small. A blurhash string per photo adds about 30 bytes. Inline LQIP adds 300 to 600 bytes per photo, so 30 photos add about 15 KB to the JSON. Both are fine. Inline base64 thumbnails of 5 KB each are not.

Prefetching

Service Worker cache

A Service Worker can store recently viewed images in Cache Storage with a cache first strategy. Revisiting a profile then costs no network. Cap the cache at, for example, 200 entries or 50 MB, and evict the oldest. Without a cap, Cache Storage grows until the browser evicts the whole origin. HTTP caching with immutable already does most of this. The Service Worker adds offline viewing and explicit control.

11. Deep dive: memory limits on mobile

Image memory is the main reason photo web apps crash on phones. iOS Safari reloads a tab that uses too much memory, and the user loses their place. Plan for it.

Interview

Most candidates talk about bytes on the network. Few talk about decoded memory. Doing the width times height times 4 math, and explaining why windowing frees it, is a strong senior signal.

12. Failure modes

13. Trade-offs

Client resize versus raw upload

Square grid versus justified versus masonry

Blurhash versus LQIP versus color

Format choice

Aggressive versus careful prefetch

14. 45-minute interview walkthrough

  1. Minutes 0 to 5. Clarify surfaces, photos or video, carousels, editing, aspect ratios, offline uploads.
  2. Minutes 5 to 10. Budgets: 390 pixel screen at 2x cap, bytes per variant, decoded memory math, 16 ms frames, CLS under 0.1.
  3. Minutes 10 to 16. Architecture: viewing path and upload path sharing a store. Draw both.
  4. Minutes 16 to 20. Data model with width, height, blurhash, base URL. API with feed pages, upload sessions, and idempotent post creation.
  5. Minutes 20 to 28. Deep dive on responsive images: srcset, sizes, allowed widths, formats, fetchpriority for LCP.
  6. Minutes 28 to 36. Deep dive on upload: worker decode, EXIF, resize, encode, IndexedDB, resumable chunks, progress.
  7. Minutes 36 to 41. Grid without shift, lightbox with <dialog>, carousel with scroll snap, stories timer and preload.
  8. Minutes 41 to 45. Memory on mobile, failure modes, and metrics: LCP, CLS, bytes per view, upload success rate, crash reloads.

15. Summary

16. Common mistakes

Worked example: posting one photo

Maya posts a portrait photo from her phone on a weak 4G connection with a 2 Mbps uplink.

  1. She taps the plus button. The upload editor chunk loads, about 60 KB. She picks a 4032 by 3024 JPEG of 4.8 MB with EXIF orientation 6, meaning rotate 90 degrees.
  2. The main thread sends the File to the worker. The worker calls createImageBitmap with orientation from the image. The bitmap is 3024 by 4032, upright. Decode takes 350 ms, but the main thread stays free.
  3. The worker makes an 810 by 1080 preview and transfers it back. The edit screen shows it in 420 ms total.
  4. Maya crops to 4:5 and picks a filter. The client stores only the crop rectangle and filter name.
  5. She taps Next and types a caption. The worker draws the crop onto an OffscreenCanvas at 1638 by 2048, applies the filter, and encodes JPEG at 0.85. Result: 610 KB. The worker closes both bitmaps.
  6. The blob is saved to IndexedDB with jobId j-41. The job status becomes queued.
  7. She taps Share. Her feed shows the post at the top with the local preview and a progress ring. She keeps scrolling.
  8. The queue calls POST /uploads and gets a session with 256 KB chunks. Chunk 1 and 2 upload. The ring shows 45 percent.
  9. She walks into an elevator. Chunk 3 fails. The queue waits 1 s, then 2 s, then 4 s. The ring shows "Waiting for network".
  10. Signal returns. The queue sends HEAD to the session. The server says 524,288 bytes received. The queue sends chunk 3 from that offset, then the final chunk. The server returns photoId ph_9.
  11. The queue calls POST /posts with Idempotency-Key: j-41. The response is lost. The retry returns the same post id. There is one post, not two.
  12. The store swaps the local preview for the CDN URL. The browser picks the 828 pixel variant for her 2x screen. The blob in IndexedDB and its object URL are deleted and revoked.

Code lab: a justified row layout

This function computes a Flickr style justified layout from aspect ratios alone. It runs before any image loads, so every box has its final size and the layout never shifts. Save as justify.mjs and run node justify.mjs with Node 18 or newer.

// photos: [{ id, w, h }]   returns boxes: [{ id, x, y, width, height }]
export function justify(photos, { containerWidth, targetHeight = 200, gap = 4 }) {
  const boxes = []
  let row = [], y = 0

  function flush(isLast) {
    if (row.length === 0) return
    const ratioSum = row.reduce((s, p) => s + p.w / p.h, 0)
    const free = containerWidth - gap * (row.length - 1)
    // last row keeps the target height so a single photo is not stretched huge
    const height = isLast ? Math.min(targetHeight, free / ratioSum) : free / ratioSum
    let x = 0
    for (const p of row) {
      const width = height * (p.w / p.h)
      boxes.push({ id: p.id, x: Math.round(x), y: Math.round(y),
                   width: Math.round(width), height: Math.round(height) })
      x += width + gap
    }
    y += height + gap
    row = []
  }

  for (const p of photos) {
    row.push(p)
    const ratioSum = row.reduce((s, q) => s + q.w / q.h, 0)
    const widthAtTarget = ratioSum * targetHeight + gap * (row.length - 1)
    if (widthAtTarget >= containerWidth) flush(false)
  }
  flush(true)
  return { boxes, totalHeight: Math.round(y - gap) }
}

const photos = [
  { id: "a", w: 4032, h: 3024 }, { id: "b", w: 1080, h: 1350 },
  { id: "c", w: 1080, h: 1080 }, { id: "d", w: 1920, h: 1080 },
  { id: "e", w: 3024, h: 4032 }, { id: "f", w: 1200, h: 800 },
  { id: "g", w: 800, h: 1200 },
]
const { boxes, totalHeight } = justify(photos, { containerWidth: 800, targetHeight: 220 })
for (const b of boxes) console.log(b.id, b.x, b.y, `${b.width}x${b.height}`)
console.log("total height:", totalHeight)
const rowEnds = new Map()                 // y -> right edge of the row
for (const b of boxes) rowEnds.set(b.y, Math.max(rowEnds.get(b.y) ?? 0, b.x + b.width))
const ends = [...rowEnds.values()].slice(0, -1)   // ignore the last row
console.log(ends.every((e) => Math.abs(e - 800) <= 2) ? "PASS full rows fill the width" : "FAIL")

Each full row ends within a pixel or two of 800, and the last row keeps a natural height. In the app, apply each box as transform: translate(x, y) with fixed width and height, then let images load into it. Try changing containerWidth to 390 to see the phone layout.

Check yourself

  1. A grid tile is 130 CSS pixels wide on a 3x phone. Which image width should it load, and why cap at 2x?
    Answer

    At 3x it needs about 390 pixels, so the 480 width. With a 2x cap it needs about 260 pixels, so the 320 width. The cap saves about half the pixels and users cannot see the difference in photos.

  2. Why is file size a poor measure of image memory use?
    Answer

    The browser draws from a decoded bitmap of width times height times 4 bytes. A 150 KB JPEG at 1080 by 1350 uses about 5.8 MB once decoded. Memory depends on pixel count, not compressed size.

  3. Name the steps a worker takes to prepare a phone photo for upload.
    Answer

    Decode with createImageBitmap and apply EXIF orientation. Apply the crop and draw onto an OffscreenCanvas at about 2,048 pixels at most. Encode with convertToBlob. Save the blob to IndexedDB and close the bitmaps.

  4. An upload fails at 70 percent. What does a resumable upload do next?
    Answer

    It waits with backoff, asks the server for the confirmed offset, and sends only the bytes after that offset. The session URL and offset are stored in IndexedDB so this also works after a reload.

  5. How do you guarantee a grid has zero layout shift?
    Answer

    Every photo carries its width and height in metadata. The grid computes every box from aspect ratios before images load, using aspect-ratio, width and height attributes, or absolute positions. Images then fill boxes that already exist.

  6. Why should the story timer wait for the image to decode?
    Answer

    On a slow network the image may take seconds to arrive. If the 5 second timer starts at once, the user sees a blank screen and the story advances before they see it.

  7. Why restrict the CDN to a fixed list of widths?
    Answer

    Each unique width is a separate transform and cache entry per photo. Arbitrary widths spread requests across many variants, lower the cache hit rate, and increase origin load and cost.

Key terms

srcset
An image attribute listing variants by width or density for the browser to choose from.
sizes
An image attribute that tells the browser the displayed width under different conditions.
Device pixel ratio
The number of physical pixels per CSS pixel on a screen.
Image CDN
A CDN that resizes, compresses, and converts images on request and caches the results.
EXIF orientation
Metadata that says how a camera image should be rotated for display.
OffscreenCanvas
A canvas that works in a Web Worker, away from the main thread.
createImageBitmap
A browser API that decodes an image asynchronously into a drawable bitmap.
Resumable upload
An upload that can continue from the last confirmed byte after a failure.
CLS
Cumulative Layout Shift, a measure of unexpected movement of visible content.
LCP
Largest Contentful Paint, when the largest visible element finishes rendering.
Blurhash
A short string that encodes a blurred preview of an image.
LQIP
Low quality image placeholder, a tiny blurry version shown before the real image.
Justified layout
Rows of photos at equal height scaled to exactly fill the container width.
Scroll snap
CSS that makes a scroll container rest at defined positions, used for carousels.

Further reading

Primary references