System Design Handbook · llms.txt
A text-sharing service lets someone paste a block of text into a web form and get back a short link, such as https://paste.example/r7k2x9a. Anyone who opens the link sees the text. People use it to share a stack trace with a colleague, a config file in a chat, or a log excerpt in a bug report. Pastebin.com is the best-known example.
The traffic in this exercise is modest, but the design still makes you decide real things. Each paste has two kinds of data. One is a small record: the paste's short code, when it was created and when it expires. The other is the text itself, which can be a few bytes or hundreds of kilobytes. Where each one lives, how expired pastes get cleaned up, and how to serve a paste that suddenly gets popular are the interesting decisions.
The same design covers a URL shortener such as Bitly. A shortener stores a long URL where this service stores text, and it answers a visit with a redirect instead of a page. The handbook covers that problem in Design a URL shortener, which goes deep on short codes, redirect status codes and redirect caching. This chapter treats short codes briefly. It spends its depth on storing paste contents, size limits, expiry, caching the read path, and counting page views.
The chapter follows the four steps from The system design interview, step by step.
There's no interviewer to answer questions here, so we'll state the use cases and assumptions ourselves.
These numbers are made-up inputs for the exercise. They don't describe any real service.
The size of one paste, counting 1 KB as 1,000 bytes:
shortlink: 7 bytes, one per character of the code.expiration_length_in_minutes: 4 bytes, a 32-bit integer.created_at: 5 bytes, a compact date and time.paste_path: up to 255 bytes, where the text lives in storage.The 255 bytes for the path is an upper bound, since a variable-length column stores only the characters it holds. Using the upper bound keeps the estimate safe.
Storage over time:
Split that into its two parts, because they'll live in different stores:
Request rates. A month has about 2.5 million seconds. (The exact figure is 30.4 days × 86,400 s ≈ 2.63 million; the round number is fine for an estimate.)
A handy conversion guide:
A few more numbers for step 4:
What these numbers tell us. On average this is a small system, and one server could handle the load. So the design is shaped by other things. The first is availability, because one server is one machine that can fail. The second is skew: one paste shared on a busy forum can get thousands of views a second while the average stays at 40. The third is growth, with 360 million pastes after three years. Note too that the text is almost four times the size of the metadata. That hints that the two belong in different stores. The estimation chapter covers this kind of arithmetic.
curl.pastes table, retrying with a new code if that one is taken,We need something like a huge hash table: give it a code, get back the paste. There are three reasonable places for the text.
This design uses option 3.
The costs are real. A cache miss now makes two round trips, and the second is slow: Amazon's performance guide puts small-object reads at "roughly 100–200 milliseconds" and suggests a cache in front when you need single-digit milliseconds. And a create writes to two stores that can't share a transaction.
A middle path is worth raising in an interview: keep small pastes in the row and move only large ones out. PostgreSQL does a version of this already. Its documentation says that when a row is wider than about 2 kB, it compresses large values and moves them "out-of-line" to a separate table. Keeping 1 KB pastes inline would save the second round trip for most reads, at the cost of two code paths.
A size limit protects everything else. Without one, a single 2 GB upload could exhaust a server's memory. Pastebin's FAQ says free accounts can create pastes up to 512 kilobytes and PRO members up to 10 megabytes. We'll use 512 KB, enforced twice: at the web server, as a maximum request body size, and in the Write API, by counting the decoded bytes. Both reject with 413 Content Too Large.
The limit barely moves the average, but it sets the worst case. One 512 KB paste read 1,000 times a second is 512 MB a second, about 4 gigabits a second of outgoing traffic. That's what the CDN in step 4 is for.
pastes tableCREATE TABLE pastes (
shortlink CHAR(7) NOT NULL,
expiration_length_in_minutes INT NULL, -- NULL means never expires
created_at DATETIME NOT NULL,
expires_at DATETIME NULL, -- created_at + length, or NULL
paste_path VARCHAR(255) NOT NULL, -- key in the object store
PRIMARY KEY (shortlink),
INDEX idx_expires_at (expires_at)
);
shortlink is the primary key. Every read looks a paste up by its code. The primary key also creates an index that the database uses to enforce uniqueness, so two pastes can never share a code.NULL.expires_at is stored and indexed. The cleanup job asks which pastes have expired, which depends on created_at + expiration_length_in_minutes. An index on created_at alone can't answer that, because two pastes created together can expire a minute or a year apart. Indexing the computed expires_at lets the job find expired rows without scanning the table.The table could live in a NoSQL key-value store instead, since every read is "get by key" with no joins. The cleanup job's "everything that expired before now" is easier in SQL, where it's a range scan on an index. We'll use a relational database. SQL or NoSQL covers the choice in general.
The code must be short, safe in a URL, and hard to guess.
0-9, a-z and A-Z, which are all safe in URLs. Base64 adds + and /, which have special meanings in URLs. Encoding is deterministic, and a k-digit result takes k steps.Two details matter in practice. First, reduce the number modulo 62⁷ before encoding. A 128-bit number in Base62 has up to 22 characters, and since 2¹²⁸ is only about one eighth of 62²², its first character can take only about 8 values. Cutting the first 7 characters therefore uses only about 8 × 62⁶ ≈ 450 billion codes. Second, add randomness. Two people behind one office network share an IP address, and if they create pastes in the same millisecond, hashing IP and time gives both the same code every time they retry.
import hashlib
import os
import time
ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
CODE_LENGTH = 7
def to_base62(num: int) -> str:
if num == 0:
return ALPHABET[0]
digits = []
while num > 0:
num, remainder = divmod(num, 62)
digits.append(ALPHABET[remainder])
return "".join(reversed(digits))
def new_shortlink(client_ip: str) -> str:
seed = f"{client_ip}|{time.time_ns()}|{os.urandom(8).hex()}"
number = int.from_bytes(hashlib.md5(seed.encode()).digest(), "big")
return to_base62(number % 62 ** CODE_LENGTH).rjust(CODE_LENGTH, ALPHABET[0])
Random codes sometimes collide with a taken one. With 360 million pastes stored, a new code collides about once in 9,800 tries (360 million ÷ 3.52 trillion). Over all three years that's roughly 18,000 collisions (360 million² ÷ (2 × 3.52 trillion)). The fix is cheap: insert, let the primary key reject a duplicate, and retry with a new code. A custom alias, if the product adds one, goes through the same insert and the same check.
The alternative is to encode numbers from a counter, which never collide. Generating the short code compares the approaches and how to hand out unique numbers across servers.
A crash between the object store write and the database write leaves one without the other. The order decides which.
So write the text first, under a key that doesn't depend on the short code, such as a UUID. Otherwise a retry after a code collision would overwrite another paste's text. A periodic sweep deletes objects that no row references once they're a day old. S3 supports this order: it gives "strong read-after-write consistency for PUT and DELETE requests," and "if a PUT request is successful, your data is safely stored." Distributed transactions covers keeping two stores in step more generally.
import uuid
from datetime import datetime, timedelta
MAX_PASTE_BYTES = 512 * 1000
def create_paste(request, client_ip, db, object_store):
text = request["paste_contents"]
size = len(text.encode("utf-8"))
if size == 0 or size > MAX_PASTE_BYTES:
raise PayloadTooLarge(size)
minutes = request.get("expiration_length_in_minutes") # None: never expires
created_at = datetime.utcnow()
expires_at = created_at + timedelta(minutes=minutes) if minutes else None
# 1. Text first, under a key that doesn't depend on the code.
paste_path = f"{expiry_prefix(minutes)}/{uuid.uuid4().hex}"
object_store.put(paste_path, text, content_type="text/plain; charset=utf-8")
# 2. Claim a code. The primary key rejects duplicates.
for _ in range(5):
shortlink = new_shortlink(client_ip)
try:
db.execute(
"INSERT INTO pastes VALUES (%s, %s, %s, %s, %s)",
(shortlink, minutes, created_at, expires_at, paste_path),
)
return {"shortlink": shortlink}
except db.UniqueViolation:
continue
raise RuntimeError("no free short code")
expiry_prefix puts each paste under a prefix for its expiry option, such as ttl-7d/ or ttl-never/. The deletion use case explains why.
The public API follows REST: each paste is a resource with its own URL, acted on with standard HTTP methods. See REST.
$ curl -X POST https://paste.example/api/v1/pastes \
-H "Content-Type: application/json" \
-d '{"paste_contents": "Hello World!", "expiration_length_in_minutes": 60}'
HTTP/1.1 201 Created
Content-Type: application/json
{
"shortlink": "r7k2x9a",
"url": "https://paste.example/r7k2x9a",
"raw_url": "https://paste.example/raw/r7k2x9a"
}
Leaving out expiration_length_in_minutes creates a paste that never expires.
Inside the system, services can talk over remote procedure calls (RPC), where one server calls a function on another as if it were local. RPC is compact for traffic you control, and REST suits outside users because any HTTP client works. RPC compares them.
pastes table.
$ curl https://paste.example/api/v1/pastes/r7k2x9a
HTTP/1.1 200 OK
Content-Type: application/json
{
"paste_contents": "Hello World!",
"created_at": "2026-10-19T14:02:11Z",
"expiration_length_in_minutes": 60,
"expires_at": "2026-10-19T15:02:11Z"
}
An unknown code gets 404 Not Found. An expired one can get 410 Gone, which says the paste existed and was removed on purpose.
Readers also use two other URLs. https://paste.example/r7k2x9a is an HTML page showing the text. https://paste.example/raw/r7k2x9a returns only the text, as text/plain, for scripts and terminals. The raw URL is often the busiest, and it's the easiest to cache, because every reader gets the same bytes.
The Read API must check expires_at on every read. Cleanup runs in the background and can run late, so a paste that expired a second ago has to look gone even if its row and file still exist.
Step 4 adds a memory cache, used cache-aside: check the cache, and on a miss read the database and object store, then fill the cache. Cache-aside explains the pattern.
DEFAULT_TTL = 3600 # seconds
MISSING = "missing"
def get_paste(shortlink, cache, replica, primary, object_store):
key = f"paste:{shortlink}"
entry = cache.get(key)
if entry is None:
row = replica.find_paste(shortlink) or primary.find_paste(shortlink)
if row is None:
cache.set(key, MISSING, ttl=60)
return 404, None
entry = {
"paste_contents": object_store.get(row.paste_path),
"created_at": row.created_at,
"expires_at": row.expires_at,
}
cache.set(key, entry, ttl=ttl_for(row.expires_at))
if entry == MISSING:
return 404, None
if entry["expires_at"] and entry["expires_at"] <= datetime.utcnow():
return 410, None
return 200, entry
def ttl_for(expires_at):
"""Never cache a paste past its own expiry."""
if expires_at is None:
return DEFAULT_TTL
seconds_left = (expires_at - datetime.utcnow()).total_seconds()
return max(1, min(DEFAULT_TTL, int(seconds_left)))
We need monthly visit counts per paste, and they don't need to be real time. Every view already passes through a web server that writes an access log line, such as:
203.0.113.7 - - [19/Oct/2026:14:02:11 +0000] "GET /raw/r7k2x9a HTTP/1.1" 200 1311
So the cheapest design counts from the logs after the fact, with nothing added to the read path. Each web server ships its logs to the object store hourly. Once a day, a MapReduce job counts views. Dean and Ghemawat's 2004 MapReduce paper from Google uses this very task as an example: counting how often each URL appears in "logs of web page requests." You write two functions.
(month, shortlink) with the value 1.An optional combiner adds up counts on each mapper machine before the shuffle, so a popular paste sends one number per machine instead of one per view. The paper describes combiners for reduce functions that are "commutative and associative," and addition is both.
import re
from datetime import datetime
VIEW = re.compile(
r'\[(?P<ts>[^\]]+)\] "GET /(?:raw/)?(?P<code>[0-9A-Za-z]{7}) HTTP/[\d.]+" (?P<status>\d{3})'
)
class MonthlyPasteViews:
def mapper(self, _, line):
"""Emit ((month, shortlink), 1) per successful view:
("2026-10", "r7k2x9a"), 1
("2026-10", "r7k2x9a"), 1
("2026-10", "bQ81zz0"), 1
"""
match = VIEW.search(line)
if match is None or match["status"] != "200":
return
month = datetime.strptime(match["ts"], "%d/%b/%Y:%H:%M:%S %z").strftime("%Y-%m")
yield (month, match["code"]), 1
def combiner(self, key, counts):
yield key, sum(counts)
def reducer(self, key, counts):
"""Total per paste per month:
("2026-10", "r7k2x9a"), 2
("2026-10", "bQ81zz0"), 1
"""
yield key, sum(counts)
The output, one row per paste per month, goes into the analytics database. The input is about 20 GB of logs a month, so this is a small job. Decide what a "visit" means before writing the mapper: this one counts every successful request, but you may want to drop bots or count each visitor once a day. Only the mapper changes. MapReduce covers the shuffle and fault tolerance in more depth.
The other approach counts as views happen. The Read API publishes a small event, {shortlink, timestamp}, to a log such as Apache Kafka, an append-only sequence of events that consumers read at their own pace. A consumer keeps running totals for a few seconds, then writes the increments to the analytics store. Event streaming explains these logs.
| Batch over access logs | Streaming view events | |
|---|---|---|
| Freshness | A day old | Seconds old |
| Change to the read path | None | Publish one event per view |
| New infrastructure | A scheduled job | A log cluster and always-on consumers |
| Fixing a counting bug | Re-run over the stored logs | Replay the log, if it still holds the events |
| Duplicates | Rare | Need care: see delivery semantics |
Real-time counts aren't required, so batch fits better here. Streaming earns its cost if the product wants a live view counter, and many systems run both, as described under Lambda vs Kappa.
One trap applies to both. Once step 4 puts a CDN in front of raw pastes, many views are answered by the CDN and never reach a web server. The job must also read the CDN's request logs, or the counts drop the day the CDN goes live.
Deleting an expired paste means removing its row and file and making sure no cache still serves it. The read path already hides expired pastes, so cleanup only reclaims space and doesn't need to be instant. If half of all pastes set an expiry, that's 5 million ÷ 2.5 million s = 2 deletions a second on average, which is easy as long as nothing scans the whole table.
A job runs every few minutes and deletes in small batches, using the expires_at index:
def delete_expired_pastes(db, object_store, cache, batch_size=1000):
while True:
rows = db.query(
"SELECT shortlink, paste_path FROM pastes"
" WHERE expires_at <= NOW() ORDER BY expires_at LIMIT %s",
batch_size,
)
if not rows:
return
for row in rows:
db.execute("DELETE FROM pastes WHERE shortlink = %s", row.shortlink)
cache.delete(f"paste:{row.shortlink}")
object_store.delete(row.paste_path) # a failure leaves a harmless orphan
Small batches keep each delete short, so locks are held briefly and replicas aren't flooded with changes. The row goes first, so readers stop finding the paste. If the file delete fails, the orphan sweep from the write path removes it later.
The job could instead mark rows as expired, a soft delete. That keeps a record for abuse reports and lets the read path return 410 Gone, but the table never shrinks. A common middle path marks the row at once and removes it 30 days later.
S3 can delete files on a schedule with lifecycle rules. A rule selects objects by key prefix or tag and expires them a set number of days after creation. That's why the write path files each paste under a prefix for its expiry option: one rule per prefix, such as ttl-7d/, cleans up those files. Amazon's documentation sets some limits:
So lifecycle rules are a cheap backstop for day-sized options. They don't remove database rows or replace the read-path check. Pastes that never expire go under a prefix with no rule.
An expired paste can linger in two caches. The memory cache already caps its TTL at the paste's remaining life. The CDN needs the same rule: raw responses carry Cache-Control: max-age set to the smaller of the default and the seconds left. CloudFront's documentation says max-age sets how long, in seconds, it keeps an object before asking the origin again, capped by its own maximum TTL. Without the header, CloudFront falls back to the default TTL, which is 24 hours unless you change it. That would keep a 10-minute paste visible for a day.
The Write API also writes to the object store; that edge is left out so lines don't cross.
Don't jump straight to this design. Scaling is a loop: benchmark with a load test, profile to find the bottleneck, fix it while weighing alternatives, and repeat. Design a system that scales to millions of users on AWS walks through that loop.
Four writes and 40 reads a second won't strain any one component. The problems are elsewhere:
Each component below fixes one of these, and each has a cost.
DNS turns paste.example into the load balancers' addresses, and with health checks it can steer clients away from a failed site (bottleneck 1).
A CDN is a network of caching servers in many locations that serves content from a server near the reader. Use it as a pull CDN for raw pastes: on a miss it fetches the paste from you once, then serves its copy until it expires. A viral raw paste becomes a handful of requests to your servers (bottleneck 3), and distant readers get lower latency. Point the CDN at the load balancer. Then every miss still passes the Read API's expiry check and gets the right Cache-Control header, which wouldn't happen if the CDN read the object store directly.
The costs: a paste removed for abuse stays visible at the edge until its copy expires, unless you also send the CDN an invalidation; and CDN-served views vanish from your web server logs. See CDNs and HTTP caching headers.
A load balancer spreads requests across identical web servers and stops sending traffic to any that fail health checks. Running many copies this way is horizontal scaling, and it removes the web tier as a single point of failure. It works because the servers are stateless: users are anonymous, so there are no sessions to share. The load balancer is now critical, so run a pair. See load balancing.
Behind the web servers sits an application layer of API servers, split into a write pool and a read pool. Reads are ten times as frequent and writes do more work each, so separate pools scale and deploy independently, and a burst of reads can't starve the create path. The cost is more services to run, plus internal load balancers. See separating the web and application layers.
A memory cache such as Redis or Memcached keeps recently read pastes in RAM. Popular pastes come back in about a millisecond without touching the database or object store (bottleneck 2), and spikes are absorbed before they reach the database (bottleneck 3). Sizing is easy: a whole day's distinct reads would take about 4.3 GB, and the hottest 20% under 1 GB, so one modest server with a replica is enough.
The costs: cached data can be stale, though pastes are never edited, so only deletion and expiry matter, and the TTL rules bound both. A cold cache sends a burst of misses, and a hot key that expires can make thousands of requests rebuild it together. Cache stampede lists the fixes.
The database becomes a primary that takes all writes and read replicas that copy its changes, an arrangement often called master-slave replication.
Four writes a second, more at peak, is well within one primary. The costs are replica lag, which is why reads of brand-new codes fall back to the primary, and promotion, which must never leave two primaries accepting writes. See primary-replica replication, active-passive failover, CAP and consistency and Availability.
S3 handles 12.7 GB of new text a month comfortably, with no disks to add. What grows is the number of objects and requests. Amazon's documentation says S3 supports "at least 3,500 PUT/COPY/POST/DELETE or 5,500 GET/HEAD requests per second per partitioned Amazon S3 prefix," and that scaling up "happens gradually," with 503 Slow Down errors meanwhile. At 4 writes a second we're far below that.
One trap: Amazon's storage class table shows that S3 Standard-IA, the cheaper class for rarely read data, bills each object as at least 128 KB and for at least 30 days. A 1 KB paste there costs as much as a 128 KB one. Keep small pastes in S3 Standard.
The MapReduce output goes into a separate analytics database. A data warehouse such as Amazon Redshift or Google BigQuery is built for the large scans and grouping queries that reports run, which would slow the serving database. See data warehouses.
Nothing in the assumptions forces this, but an interviewer may ask about 100 times the traffic. Start with SQL tuning: every query on an index, small rows, pooled connections. Then:
pastes table by a hash of shortlink. Every read knows the code, and random codes spread evenly.Moving the table to a NoSQL key-value store is another option. It has the right shape and scales writes by adding nodes. The cost is the cleanup job's range query on expires_at, which most key-value stores don't support directly, though some offer built-in per-item expiry instead.
Text in the object store or in the database? The object store brings durability for free, a small database, and raw pastes a CDN can serve. It costs a second, slower read on cache misses and two writes with no shared transaction. At 360 GB over three years, the database could hold the text too. I'd use the object store with a memory cache in front, and mention keeping pastes under a few kilobytes inline. See where the text lives.
Random codes or a counter? Random codes are unguessable and need no coordination, but inserts sometimes collide, about once per 9,800 creates at the worst point. A counter never collides but needs unique numbers across servers, and sequential codes let anyone list every paste unless they're scrambled. Unlisted sharing is the main use, so I'd pick random codes. See generating the short code.
SQL or NoSQL for the metadata? Reads are lookups by key, which suits key-value stores. Cleanup is a range query on expiry, which suits SQL. At 4 writes a second and 98 GB, one relational primary with replicas is enough. See SQL or NoSQL.
How do expired pastes go away? Only the read-path check is exact. A cleanup job, lifecycle rules and per-item expiry in a store all reclaim space late, by minutes or, for S3 lifecycle, by days. I'd use the read check for correctness, the job for rows and files, and lifecycle rules as a backstop.
How long should caches keep a paste? Longer TTLs mean less load; shorter ones make removals visible sooner. Expiry is known in advance, so TTLs can follow it exactly. Abuse takedowns aren't, so they need explicit cache deletes and CDN invalidation. I'd cap the default at about an hour. See cache invalidation.
Batch or streaming analytics? Batch is cheap, leaves the read path alone and is easy to re-run. Streaming gives live counts for the price of a log cluster and duplicate handling. With no real-time requirement, I'd use batch. See batch processing.
What stops abuse? Anonymous creation needs rate limiting by IP address. Pastes are untrusted text shown in browsers, so serve raw pastes as text/plain with X-Content-Type-Options: nosniff, escape text in the HTML page, and ideally serve raw pastes from a separate domain so a crafted paste can't run script alongside your cookies. See cross-site scripting.
The metadata is unchanged at about 98 GB over three years. The text grows tenfold: 10 KB × 10 million = 100 GB a month, and 100 GB × 36 = 3.6 TB over three years.
That strengthens the case for the object store. With text in the database, it would hold about 3.7 TB, so backups, replicas and failover would move almost forty times more data than the metadata needs. The inline option weakens too, since most pastes would now be above a 2 kB threshold. Read bandwidth rises from about 0.4 to about 3.2 megabits a second, which is still small.
In the first design, every request hits the single Read API, which reads the database and then the object store. At 100–200 ms per object read, Little's Law puts 5,000 × 0.1 to 0.2 s = 500 to 1,000 requests in flight at once, each holding a connection and memory. Outgoing traffic is 5,000 × 300 KB = 1.5 GB a second, about 12 gigabits a second, more than a typical server's network card.
In the scaled design, the CDN answers nearly all of it from the edge. Your servers see about one request per edge location each time the cached copy expires, and those hit the memory cache. The remaining risk is the moment the copy expires everywhere at once, which request coalescing at the CDN or a lock in the cache layer handles.
The HTML page goes through the Read API, which checks expires_at on every request, so the data is right. Something in front of the raw URL is serving a stale copy, most likely the CDN. The raw response was cached with a fixed max-age such as an hour, or with no Cache-Control header, in which case CloudFront keeps it for its default TTL, 24 hours unless changed.
The fix is to set max-age on raw responses to the smaller of the default and the seconds left, and to check that the CDN's minimum TTL isn't raising it. A lifecycle rule wouldn't help, because rules count in whole days and run late.
The analytics job counts from web server access logs. Since launch, most raw-paste views have been answered at the edge and never reached a web server, so they're missing from the job's input.
Ship the CDN's request logs to the object store and teach the mapper both formats. Then avoid counting twice: a CDN miss appears in both the CDN log and the web server log. Count from the CDN log for URLs the CDN serves and from the web server log for the rest.
The object store holds a file under a random key that no row points to. The client saw an error or timeout and probably retries, which uploads a new file and inserts a row. Nobody has a code for the first file, so nobody can reach it, and it only costs a little storage. The orphan sweep lists objects over a day old, checks which keys appear in paste_path, and deletes the rest.
With the opposite order, the crash would leave a row pointing to a missing file, and anyone with the code would get an error. That's why the text goes first, under a key independent of the code.
The read must claim the paste atomically, so two people opening the link together can't both see it. A single DELETE FROM pastes WHERE shortlink = %s RETURNING paste_path, or a conditional update that sets a "burned" flag, succeeds for exactly one request. It must run on the primary, because replicas lag.
Every cache must be skipped: the Read API doesn't cache these pastes, and responses carry Cache-Control: no-store so neither the CDN nor the browser keeps a copy. There's also a product trap. Chat apps and email clients often fetch a link to build a preview before anyone clicks, which would burn the paste. A common fix is a "click to reveal" page, burning the paste only on that second request.
Cache-Control headers with its own TTL settings.Previous: Batch processing and distributed computing · Next: Design a URL shortener (like TinyURL or Bitly)