System design practice

File Previews and Thumbnails

medium Based on a system published by Dropbox queues async cdn object-storage read-heavy real-world

Dropbox's Riviera: render each output once, in the background, and serve it from a CDN.

Solve it in your browser Read the lesson first

Every file in Dropbox gets a thumbnail in the file list, and most documents can be opened as a preview in the browser without downloading them. Dropbox's content processing platform, Riviera, makes those derived outputs: a central coordinator takes each request, checks for a stored result, and dispatches the work to pools of workers, one pool per kind of transformation. A PowerPoint deck, for example, is converted to PDF and each page rendered as an image.

The expensive part is the transformation; the cheap part is serving its result again. So Riviera pre-warms: it generates the outputs of new files in the background, before anyone asks, and stores them. When a preview was not pre-warmed, it has to be generated while the user waits.

Design the upload, the background generation and the two read paths.

Functional requirements

Name the thumbnail workers thumbnailer, the preview workers previewer and the derived-output store derived: the capacity and the tests in problem.proschi refer to them, and to the use case and scenario names above.

Scale

The rates and worker speeds are assumptions for the exercise: Dropbox has published only the platform's total, hundreds of thousands of transformations a second.

Constraints

What is given

problem.proschi declares the user and originals, the object storage that already holds the uploaded files (four replicas), the speed and price of a thumbnail worker and of a preview worker, the traffic, the requirements and the tests. Add the upload API, the queue, the coordinator, the two worker pools, the derived-output store, the CDN, the connections and the four use cases.

What this model leaves out

Based on

How your design is checked

You write the design as text in Proschi. Tests run in your browser: a simulation of the traffic above checks latency, availability, cost and what happens when a machine fails. How the simulation works.

Start designing

Lesson · 12 min read

Learn it: File Previews and Thumbnails #

File Previews and Thumbnails: generate once, in the background, and serve many times #

Dropbox shows a thumbnail for every file and a browser preview for most documents. The system that makes them, Riviera, grew from a preview service into a platform that runs hundreds of thousands of transformations a second. This lesson builds its core idea: keep the expensive work off both the upload path and the view path.

What you'll learn #

The problem, explained #

Who uses it. Every Dropbox user: the file list needs a thumbnail per file, and opening a document in the browser needs its pages rendered as images. Behind them, other teams use the same outputs; Dropbox's post mentions that one 160×160 thumbnail serves both previews and machine-learning pipelines, so it is made once for both.

What makes it hard. Transformations are slow and varied. A thumbnail is quick, but a PowerPoint preview means converting the deck to PDF and rendering each page as an image. If any of that runs while a user waits, the user feels it; if it runs every time someone looks, the worker fleet grows with views instead of with uploads.

Functional requirements.

Non-functional requirements. Upload p99 under 200 ms and durable; thumbnail views p99 under 100 ms and 99.99% available; preview opens under 1.5 s; new outputs ready within 3 s at p99; any machine can fail; at most $12,500 a month.

What the tests check:

Back-of-the-envelope #

uploads, each one pre-warm job
1k/s
previews to render (600 pre-warmed + 40 on view)
640/s
thumbnail views
50k/s
thumbnail views that miss the edge
2.5k/s
preview opens that reach the coordinator
400/s

All of these come from the statement's scale, which is an assumption for the exercise: Dropbox has published the platform's total throughput, not per-product rates.

QuantityArithmeticResult
Thumbnails to render1 per upload1,000/s
Previews pre-warmed60% × 1,000600/s
Previews generated on view2% × 2,00040/s
Thumbnail workers busy1,000 ÷ 100 per worker10
Preview workers busy640 ÷ 40 per worker16
Thumbnail views reaching derived5% × 50,0002,500/s
Preview opens past the edge20% × 2,000400/s

Two comparisons make the design obvious. If thumbnails were rendered on every edge miss instead of stored, the thumbnail pool would face 2,500 renders a second from views on top of 1,000 from uploads: three and a half times the work, growing with popularity rather than with new files. And if the upload waited for its preview, its latency would include half a second of rendering plus any queueing in the preview pool.

Concepts #

Pre-warming in the background #

The upload's job is narrow: make the original durable and tell someone there is work to do. It writes the file to object storage, sends a message to a queue, and answers. A message to a queue is fast and does not depend on the workers being healthy, so a backlog of previews never slows an upload.

Pre-warming is Dropbox's word for generating outputs ahead of demand: a job from that queue asks the coordinator to make the new file's thumbnail and preview and store them, so that the first viewer finds them ready. It trades CPU and storage now for latency later. Dropbox's 2021 post on the subject says those costs were considerable at their volume, which is why they later trained a model to skip pre-warming previews for files unlikely to be opened; in an offline test it rejected about 40% of pre-warm requests. That is the "Thumbnail only" scenario here.

What it costs: an output is not there the instant the upload finishes, so the file list shows a placeholder for a moment, and some pre-warmed previews are never viewed. What it buys: uploads at queue speed, and views that almost never wait for a worker.

Generate once, serve many #

A thumbnail of a given version of a file never changes. That makes it the ideal cached object: compute it once, store it under a key that includes the file's version, and serve it to every viewer after that. A new version of the file gets a new key, so nothing ever has to be invalidated.

The store of derived outputs is object storage: durable, cheap per gigabyte and scaling out with requests. Losing an output is not a disaster (it can be regenerated from the original), but regenerating it costs a worker's time, so keeping it is the cheaper choice.

The one exception is a preview nobody made in advance. Then the coordinator checks the store, finds nothing, reads the original, has a preview worker render it and stores the result before answering, so the second viewer gets the stored copy. Dropbox's post describes exactly this: on a cache miss, the preview is generated on the fly while the user waits. Keeping that path rare is the point of pre-warming.

Sizing a worker pool #

A worker pool is sized like any server pool: the rate it must handle divided by what one worker handles, then headroom. Here a preview worker turns out 40 previews a second, so 640 a second keeps 16 of them fully busy. At 16 they would run at 100%, with no room for a burst or a lost machine. Aim for about 70%: 16 ÷ 0.7 is 23, plus one to lose. 24 workers run at 67%, and with one lost, 23 run at 70%.

Thumbnails are the same arithmetic with different numbers: 1,000 a second at 100 per worker is 10 busy workers, about 15 with headroom. The two pools come out different sizes because their jobs differ by an order of magnitude in cost, which is the case for keeping them separate.

Deep dive Why one pool per transformation

Riviera gives each kind of transformation its own backend workers. Each pool is then sized, scaled and deployed for its own load, and a flood of expensive document conversions cannot starve cheap thumbnails. A shared pool has to be sized for the sum, and a request's latency depends on what happens to be ahead of it. The coordinator is what keeps this manageable: it composes a request into steps (a PowerPoint preview is a PDF conversion, then a page render) and sends each step to the pool that owns it, so a new format is a new worker type, not a change to every pool.

Serving from the edge #

Thumbnails are small, immutable and requested 50,000 times a second. That is a CDN's job. With 95% of views answered at the edge, only 2,500 a second reach the derived store, which four object storage replicas take easily. Without a CDN, all 50,000 would go through your own servers to the store: dozens of API replicas and a much larger store, for bytes that never change.

Previews go through the CDN too. A preview miss at the edge goes to the coordinator rather than straight to the store, because only the coordinator can generate a missing page; Dropbox's post notes that the coordinator caches responses so workers are protected from repeated work.

Designing it step by step #

1. Scope. Ask which outputs exist (thumbnails, previews), how often each is viewed compared with how often files are uploaded, and whether a user may see a placeholder for a moment after upload. That last answer is what permits doing the work asynchronously.

2. The write path. User → upload API → originals (synchronous, durable), then an asynchronous send to the queue, then 201. Nothing about thumbnails or previews here.

3. The processing path. "Pre-warm" starts at the queue: the coordinator reads the original, calls the thumbnail pool, calls the preview pool when the file is likely to be opened, writes the outputs to derived, and acknowledges the job. Two scenarios, one per decision.

4. The read paths. Both start at the CDN. A thumbnail miss reads derived. A preview miss goes to the coordinator, which reads derived and, only when the page is not there, renders and stores it before answering.

5. Sizing and checking. Size the two pools from the arithmetic above, give every component at least two replicas, and check the bill: the preview pool is the largest line. Then read the tests' verdict and the analysis: the upload's p99 should not move when you change the preview pool's size.

Common mistakes #

Render the thumbnail inside the upload (wrong/upload-renders-thumbnail). Tempting, because the file list then never shows a placeholder. But every upload now waits for a worker, the thumbnail pool takes both the upload's renders and the pre-warm's, and a slow pool slows uploads. It fails Uploads never wait for processing and the upload's p99.

Render again on every edge miss (wrong/transform-on-every-view). The thumbnail is made but never kept, so each CDN miss reads the original and calls the thumbnail pool. The pool's load grows with views, 2,500 extra renders a second, and saturates. It fails Views are served from stored outputs and the thumbnail view's p99.

Size the preview pool like the thumbnail pool (wrong/preview-pool-sized-like-thumbnails). Fifteen workers is right for thumbnails, but a preview worker does 40 a second, not 100, so 15 of them can do 600 against 640 needed. The pool saturates before any worker is even lost, and everything that waits for a preview queues behind it. It fails the p99 of Pre-warm and of Open preview, and survive any node failure.

Serve thumbnails through the API (wrong/thumbnails-through-the-api). Every thumbnail view goes through your own servers to the store. Those saturate at 50,000 requests a second, and sizing them for it costs more than the budget, for bytes a CDN would serve at the edge. It fails Views are served from stored outputs and the thumbnail view's p99.

Other classic mistakes.

In the interview #

Open with the asymmetry: "a transformation is expensive and its output is immutable, so do it once, off the request path, and cache the result everywhere." Then draw three paths: upload, processing, view.

Likely questions, with short answers:

Further reading #

Now design it

Review cards for this problem

Short questions on the ideas it needs, from the review cards. Review them daily so they stick.

More system design problems