Module 01 · Lesson 13 of 14Free

Design: a URL shortener on a single server

Level

Intermediate

Topic

System design fundamentals

Reading time

30 min

A seller shares a festival offer through Kartly Links. In the first minute, 1,000 shoppers a second open its short address. The team must serve them from the existing eight-core server, alongside the store.

How can we create unique short links and redirect shoppers quickly without adding another server?

All link-service traffic, resource budgets and benchmark results below are assumptions for this lesson. They are not measured Kartly statistics. Kartly remains at its one-server stage, with one PostgreSQL database.

A short code is a small identifier such as aB7k2Q9x. The database maps it to a longer destination address. Opening the short address returns a redirect: an HTTP response telling the browser where to go next.

The design needs two paths. Sellers create mappings. Shoppers read them. The second path will dominate traffic, but the first determines whether every redirect stays correct.

Requirements set the server’s boundaries

Start with product questions, using the distinction from Functional and non-functional requirements.

For this scenario, the team proposes a server-side redirect target of p95 below 20 ms. That excludes the shopper’s network and the destination page load. A fast redirect cannot make a slow product page fast.

An acknowledged creation must survive an application restart. The database owns permanent mappings; application memory cannot be their only home.

One server is a hard constraint, not an availability guarantee. A host failure interrupts the store and its short links together. The team accepts that limitation for this version.

We also exclude custom aliases, previews and destination editing. Supporting arbitrary external destinations would require a separate abuse policy. Restricting destinations keeps a seller’s link from becoming a route to an unrelated phishing page.

The boundary is now clear. Next, we need to know whether the workload fits inside it.

Small writes justify a simple start

Assume sellers create 2,000 links each day. Redirect traffic normally reaches about 50 requests a second, then peaks at 1,000.

These are link-service estimates. They do not replace the store’s existing workload.

Following Capacity estimation, separate storage, writes and peak reads.

Assume a mixed-workload test, including the store, leaves capacity for about 1,500 additional mapping reads a second within the latency target. Our initial peak fits that assumed result.

These estimates justify starting with direct database lookups. They do not prove capacity. Long URLs, connection waits and shared disk activity could invalidate the assumptions.

The first implementation should expose those costs rather than hide them behind extra infrastructure.

Version 1 stores every mapping

The Links application runs as a small service on the existing host. PostgreSQL also lives there. We can run several application worker processes without adding physical servers; Server concurrency explains that distinction.

The create path

1. The seller sends a destination to the application.
2. The application authenticates the seller and validates the destination.
3. It generates a candidate code.
4. PostgreSQL attempts to insert the mapping.
5. After the insert commits, the application returns the short address.

The response must come after commit. Otherwise, a seller could share an address that never became permanent.

The redirect path

1. A browser requests /aB7k2Q9x.
2. The application checks the code’s format.
3. PostgreSQL looks up that exact code.
4. The application returns a redirect with the saved destination.
5. The browser makes a separate request to Kartly.

The shortener does not download or proxy the product page. It only returns an address. This keeps images and page rendering outside its resource budget.

An unknown code produces 404. A database timeout produces 503, not 404: unavailable storage does not mean the link is absent. Those meanings follow HTTP’s distinction between a missing resource and temporary service unavailability.^{1RFC 9110: HTTP SemanticsRoy T. Fielding, Mark Nottingham and Julian Reschke, RFC Editor, 2022}

The read path is short. The harder question is how creation assigns a code without ever overwriting someone else’s mapping.

Codes need allocation, not just randomness

A code can use digits, lowercase letters and uppercase letters. That gives an alphabet of 62 characters.

Encoding a number with that alphabet is called base62. With the alphabet 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ, the number 61 becomes Z, and 62 becomes 10.

There are three useful ways to allocate codes.

The simplest random design checks whether a candidate exists, then inserts it. That separate check is unsafe under concurrency: another request can insert the candidate between those operations.

Instead, attempt the insert directly. PostgreSQL’s ON CONFLICT DO NOTHING skips a conflicting insert. RETURNING reports only successfully inserted rows.^{3INSERTPostgreSQL Global Development Group, PostgreSQL 18 Documentation, 2025}

A large space still has collisions

That is the chance for the next attempt, not the chance of any collision across the whole year. We still require the unique constraint.

A collision is ordinary control flow. Repeated collisions are an operational signal: perhaps the generator is broken. Bound the attempts and return an error rather than looping forever.

The next step is to make the database contract precise enough for the allocator to use safely.

The database owns the invariant

PostgreSQL owns this schema:

CREATE TABLE short_links (
    code        VARCHAR(8) COLLATE "C" PRIMARY KEY,
    seller_id   BIGINT NOT NULL,
    target_url  TEXT NOT NULL,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
    CHECK (code ~ '^[0-9A-Za-z]{8}$'),
    CHECK (octet_length(target_url) BETWEEN 1 AND 2048)
);

The invariant is simple: one code identifies at most one destination.

The primary key serves both the exact-code lookup and uniqueness enforcement. We need no destination index because this version never searches by destination. Indexes develops that mechanism further.

Codes are case-sensitive. The application and database must treat aB7k2Q9x differently from Ab7k2Q9x. The explicit collation makes the intended comparison rule visible.

seller_id comes from authenticated identity, not the request body. It records ownership without adding a seller-list endpoint. If that endpoint becomes necessary, add the index for its actual query.

The application validates a destination before this insert:

INSERT INTO short_links (code, seller_id, target_url)
VALUES ($1, $2, $3)
ON CONFLICT (code) DO NOTHING
RETURNING code, target_url;

One returned row means allocation succeeded. No returned row means the candidate collided. A timeout is neither outcome; treat it as an uncertain result, not permission to claim success.

The insert adapter must finish its transaction before returning success. Concurrent inserts for the same code may wait for each other before the conflict is resolved. PostgreSQL documents that unique-index conflicts can block concurrent inserts.^{3INSERTPostgreSQL Global Development Group, PostgreSQL 18 Documentation, 2025}

The allocator has one job

These examples belong to the Links application. The supplied insert callback executes the statement above and returns only after commit. It returns false only for a code conflict; database failures raise an error.

Python:

import secrets
from collections.abc import Awaitable, Callable

ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
Insert = Callable[[str, int, str], Awaitable[bool]]

async def create_link(
    seller_id: int,
    target_url: str,
    insert: Insert,
) -> str:
    for _ in range(5):
        code = "".join(secrets.choice(ALPHABET) for _ in range(8))
        if await insert(code, seller_id, target_url):
            return code
    raise RuntimeError("Code allocation failed")

TypeScript, using Node.js’s built-in crypto module:

import { randomInt } from "node:crypto";

const ALPHABET =
  "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";

type Insert = (
  code: string,
  sellerId: number,
  targetUrl: string
) => Promise<boolean>;

export async function createLink(
  sellerId: number,
  targetUrl: string,
  insert: Insert
): Promise<string> {
  for (let attempt = 0; attempt < 5; attempt++) {
    const code = Array.from(
      { length: 8 },
      () => ALPHABET[randomInt(ALPHABET.length)]
    ).join("");
    if (await insert(code, sellerId, targetUrl)) return code;
  }
  throw new Error("Code allocation failed");
}

There is no “is this code free?” request. The insert is the decision point.

A database error must not become false in the adapter. Otherwise, an unavailable database looks like five collisions and hides the real failure.

Allocation is now race-safe. We still need a clear contract for callers, especially callers that retry.

The API separates creation from navigation

The Links application owns both endpoints:

Creation is deliberately not idempotent in this version. Two successful requests may create two links to the same destination. That matches our product requirement, but a client retry after a timeout can leave an unused alias.

If the product later promises one campaign record per creation attempt, add an idempotency key: a caller-provided identifier reused across retries. That is a separate requirement from code uniqueness.

POST /api/links HTTP/1.1
Host: ktly.example
Authorization: Bearer seller-session
Content-Type: application/json

{
  "target_url": "https://kartly.example/products/381?campaign=festival"
}

HTTP/1.1 201 Created
Content-Type: application/json
Cache-Control: no-store

{
  "code": "aB7k2Q9x",
  "short_url": "https://ktly.example/aB7k2Q9x"
}

Validation parses an absolute URL, then checks the scheme and hostname. It requires HTTPS and exactly kartly.example, rejects credentials and control characters, and limits the stored URL to 2,048 UTF-8 bytes.

A string-prefix test is not enough: kartly.example.attacker.example is a different hostname. The application also checks that the path matches a supported product route. It does not fetch the destination during creation.

These are our endpoint choices, not additional guarantees from the status codes.

Redirect headers are a product decision

HTTP/1.1 302 Found
Location: https://kartly.example/products/381?campaign=festival
Cache-Control: no-store
Content-Length: 0

We choose a temporary redirect rather than advertising a permanent move. HTTP defines 302 as a temporary location supplied through Location.^{1RFC 9110: HTTP SemanticsRoy T. Fielding, Mark Nottingham and Julian Reschke, RFC Editor, 2022}

We also explicitly disable HTTP response storage. no-store instructs compliant HTTP caches not to store the response. This does not forbid our application from caching database mappings internally.^{2RFC 9111: HTTP CachingRoy T. Fielding, Mark Nottingham and Julian Reschke, RFC Editor, 2022}

That choice keeps navigation reaching our service. If reducing origin traffic later matters more, we could permit short-lived browser caching. We would then lose some visibility into visits and some control over already-cached responses.

For now, every navigation reaches Links. That makes repeated lookups our next cost to address.

Repeated reads justify a local cache

A cache stores recently used mappings in application memory. A hit finds the code there. A miss loads it from PostgreSQL.

The create path is unchanged. Cache population is optional after commit; correctness never depends on it.

The updated read path is:

1. Validate the code format.
2. Check the worker-local cache.
3. On a usable hit, return the saved destination.
4. On a miss, query PostgreSQL by primary key.
5. Cache a successful lookup, then return the redirect.
6. Do not cache database errors as missing links.

Set an entry’s lifetime to one minute in this scenario. That lifetime is its time to live, or TTL. It bounds residence time; it is not needed to refresh immutable destinations.

A simple policy evicts the entry unused for the longest time when capacity is full. This favors recently popular campaigns without requiring a prediction of tomorrow’s traffic.

Keep the cache disposable and bounded

These examples implement the lookup mechanism inside one event-loop worker. load reads PostgreSQL asynchronously and returns null only when the code is absent.

Python:

from collections import OrderedDict
from collections.abc import Awaitable, Callable
from time import monotonic

Loader = Callable[[str], Awaitable[str | None]]

class LinkCache:
    def __init__(self, capacity: int = 10_000) -> None:
        if capacity < 1:
            raise ValueError("capacity must be positive")
        self.capacity = capacity
        self.entries: OrderedDict[str, tuple[str, float]] = OrderedDict()

    async def resolve(self, code: str, load: Loader) -> str | None:
        item = self.entries.pop(code, None)
        if item is not None and item[1] > monotonic():
            self.entries[code] = item
            return item[0]

        target = await load(code)
        if target is not None:
            self.entries.pop(code, None)
            self.entries[code] = (target, monotonic() + 60)
            while len(self.entries) > self.capacity:
                self.entries.popitem(last=False)
        return target

type Loader = (code: string) => Promise<string | null>;
type Entry = { target: string; expires: number };

export class LinkCache {
  private readonly entries = new Map<string, Entry>();

  constructor(private readonly capacity: number = 10_000) {
    if (!Number.isInteger(capacity) || capacity < 1) {
      throw new Error("capacity must be a positive integer");
    }
  }

  async resolve(code: string, load: Loader): Promise<string | null> {
    const item = this.entries.get(code);
    this.entries.delete(code);
    if (item !== undefined && item.expires > performance.now()) {
      this.entries.set(code, item);
      return item.target;
    }

    const target = await load(code);
    if (target !== null) {
      this.entries.delete(code);
      this.entries.set(code, {
        target,
        expires: performance.now() + 60_000
      });
      while (this.entries.size > this.capacity) {
        const oldest = this.entries.keys().next();
        if (oldest.done) break;
        this.entries.delete(oldest.value);
      }
    }
    return target;
  }
}

These functions are not complete HTTP handlers. The surrounding application handles validation, deadlines and response headers.

Concurrent misses may perform duplicate reads. They cannot change the saved destination. A per-code shared in-progress lookup can reduce that duplication later.

For threaded use, cache mutations need synchronization. These examples assume mutations run on one event-loop thread.

Cache placement later compares more locations. Here, the immediate question is whether this small addition removes enough work.

Growth changes the limiting resource

Assume the cache hits on 95% of redirects. That is a traffic assumption, not a property of having a cache.

Also assume a hit costs 0.1 ms of application CPU. A miss still costs 0.5 ms.

For a scenario with four workers, each holding 10,000 entries, assume an average cached entry costs 2 KB. That gives an estimated 80 MB across workers. Runtime overhead varies, so reserve more and measure memory rather than treating an entry count as a byte limit.

A popular link helps caching. Uniform requests across millions of codes may not. If the hit rate falls to zero, the cached design approaches the original database workload.

At 100×, a larger allowed host, cheaper request handling or browser caching might help. None is an automatic answer. If measurements still exceed one machine’s limits, we must reject excess traffic or revisit the hard constraint.

The later URL-shortener design addresses a different deployment boundary. We do not introduce that architecture here.

A design that fits steady traffic still needs a plan for the moment its cache disappears.

Restarting exposes the uncached system

When workers restart, their caches are empty. Previously cheap hits become database reads.

Cap concurrent database operations across all Links workers. For this scenario, start with a combined limit of 20, then tune it against the store’s workload. A request also needs a deadline; a small connection allowance without deadlines can still become permanently occupied.

When the allowance is exhausted, permit only a short, bounded queue. Beyond that, return 503. Some shoppers see a retryable error, but the service avoids consuming unbounded memory and blocking the store.

Do not fill the cache before committing a new mapping. A crash between those operations could expose a link that existed only in memory.

Keep recoverable backups and verify restoration separately from restart behavior. With one serving host, backups help recovery; they do not provide uninterrupted service.

We now have a fast normal path, an explicit overload boundary and an honest host-failure limitation.

Your turn

Common mistakes

• Checking before inserting. Another creator can win between those operations. Let the unique constraint decide.
• Overwriting on conflict. A seller’s published address must never start pointing to someone else’s product.
• Writing a click counter on every redirect. That adds a write workload the requirements did not request.
• Returning 404 on database errors. It tells shoppers a valid campaign does not exist.
• Growing the cache without a limit. Cache memory competes with the application, PostgreSQL and the store.

Each mistake moves a cost or failure into a less visible place. Keep the permanent mapping and the request’s resource budget explicit.

Going deeper

The next load-testing lab asks whether these assumed limits match a server’s measured behavior.

Check your understanding

Summary