Create compact links, resolve them globally, and count clicks without slowing redirects.
Choose a path, then play or step through exactly how the call moves between components.
The caller starts the operation at Browser / SDK with a stable request and retry identity.
The design separates the latency-sensitive online path, the correctness-critical durable transition, and asynchronous projection or repair work. Each chapter below explains one decision shown in the diagrams.
State assumptions before choosing technology. The supplied workload is 120K peak redirects/s · 6B links · p99 < 100 ms. Convert it into peak throughput, retained records, bandwidth, and failure budget; then connect each number to a component.
| Dimension | Working estimate | Design implication |
|---|---|---|
| Traffic | 120K peak redirects/s · 6B links · p99 < 100 ms | Separate online compute, durable state, and asynchronous consumers. |
| Peak factor | 5–10× average | Admission control, autoscaling headroom, and hot-key protection. |
| Stored state | write rate × retention × record bytes | Partition count, indexes, compaction, backup, and archival tier. |
| Network | peak operations × payload size | Batching, compression, edge placement, and egress budget. |
| Availability | 99.9–99.99% | Multi-zone replicas, tested failover, and dependency error budgets. |
| Recovery | RPO/RTO by invariant | Ack boundary, replay retention, reconciliation, and operator runbooks. |
POST /v1/linkscreate alias with idempotency keyGET /{code}cache-first 301/302 redirectPATCH /v1/links/{code}versioned destination editGET /v1/links/{code}/statsaggregated clickslinks(code PK, long_url, owner_id, redirect_type, version, expires_at) idempotency(owner_id, key UNIQUE, code, response) click_event(event_id, code, occurred_at, region, referrer_hash) INDEX links(owner_id, created_at DESC)
# Command envelope
operation: POST /v1/links
request_id: req_01J...
idempotency_key: idem_7f2...
aggregate_key: url-shortener_123
expected_version: 17
payload: {...}
# Durable event
event_id: evt_01J...
aggregate_key: url-shortener_123
event_type: url_shortener_committed
schema_version: 3
trace_id: tr_8ac...The authoritative aggregate and idempotency record share a transactional or conditional-write boundary. Event streams, search indexes, caches, analytics, and dashboards are rebuildable projections.
↑ topThe boxes are not a shopping list. Each boundary exists because it owns a different invariant, scaling dimension, data lifecycle, security policy, or failure domain. The table makes those choices explicit and shows when the design should remain simpler.
| Component | Owned responsibility | Why separate it | Rejected alternative | Cost and evolution trigger |
|---|---|---|---|---|
| Browser / SDK | Owns one bounded domain decision, transition, or operational capability. In this design it participates in: Validate and canonicalize the destination; run synchronous deny-list checks. | Separates a distinct scale, ownership, policy, or failure boundary. It prevents the external caller from also owning the contract and failure behavior of Anycast DNS. | Keep this behavior inside an adjacent service. Prefer that simpler option until independent scale, ownership, policy, or failure isolation is measurable. Here that simpler choice would couple “Viral code overloads one cache shard” to the external caller. | Costs an interface, deployment, telemetry, ownership, and failure mode. Keep it in-process first; extract when independent scale or reliability pays for the boundary. Measure the latency, saturation, lag, or mismatch at the Browser / SDK boundary before extracting or scaling it. |
| Anycast DNS | Owns one bounded domain decision, transition, or operational capability. In this design it participates in: Reserve a numeric ID range locally, allocate one ID, and Base62 encode it. | Separates a distinct scale, ownership, policy, or failure boundary. It prevents Browser / SDK from also owning the contract and failure behavior of CDN / Edge. | Keep this behavior inside an adjacent service. Prefer that simpler option until independent scale, ownership, policy, or failure isolation is measurable. Here that simpler choice would couple “Client times out after alias commit” to Browser / SDK. | Costs an interface, deployment, telemetry, ownership, and failure mode. Keep it in-process first; extract when independent scale or reliability pays for the boundary. Measure the latency, saturation, lag, or mismatch at the Anycast DNS boundary before extracting or scaling it. |
| CDN / Edge | Owns authentication, validation, quotas, deadlines, and routing. In this design it participates in: Conditionally insert code→URL; custom aliases use a uniqueness constraint. | Removes repeated work from the latency-critical path. It prevents Anycast DNS from also owning the contract and failure behavior of Redirect API. | Read authoritative storage for every request. Simpler initially, but latency and source-of-truth load scale together and a hot key becomes a database incident. Here that simpler choice would couple “Editable destination races with cached redirect” to Anycast DNS. | Costs invalidation, staleness, stampede protection, and memory. Add or split it only after the workload (120K peak redirects/s · 6B links · p99 < 100 ms) proves repeated reads dominate. Measure the latency, saturation, lag, or mismatch at the CDN / Edge boundary before extracting or scaling it. |
| Redirect API | Owns authentication, validation, quotas, deadlines, and routing. In this design it participates in: On redirect, read edge/process cache, then Redis, then the owning metadata shard. | Separates a distinct scale, ownership, policy, or failure boundary. It prevents CDN / Edge from also owning the contract and failure behavior of URL Create API. | Put protocol, authentication, quotas, and business transitions in one process. Acceptable at low scale, but it couples external traffic risk to domain releases. Here that simpler choice would couple “ID worker loses its range lease” to CDN / Edge. | Costs another hop, policy distribution, and a high-blast-radius fleet. Introduce it when many clients or services need one protocol and protection boundary. Measure the latency, saturation, lag, or mismatch at the Redirect API boundary before extracting or scaling it. |
| URL Create API | Owns authentication, validation, quotas, deadlines, and routing. In this design it participates in: Return redirect immediately and publish a sampled/deduplicated click event asynchronously. | Separates a distinct scale, ownership, policy, or failure boundary. It prevents Redirect API from also owning the contract and failure behavior of Redis Cache. | Put protocol, authentication, quotas, and business transitions in one process. Acceptable at low scale, but it couples external traffic risk to domain releases. Here that simpler choice would couple “Analytics lag grows without affecting redirects” to Redirect API. | Costs another hop, policy distribution, and a high-blast-radius fleet. Introduce it when many clients or services need one protocol and protection boundary. Measure the latency, saturation, lag, or mismatch at the URL Create API boundary before extracting or scaling it. |
| Redis Cache | Serves a low-latency, disposable projection with authoritative fallback. In this design it participates in: Validate and canonicalize the destination; run synchronous deny-list checks. | Removes repeated work from the latency-critical path. It prevents URL Create API from also owning the contract and failure behavior of Short-Code Router. | Read authoritative storage for every request. Simpler initially, but latency and source-of-truth load scale together and a hot key becomes a database incident. Here that simpler choice would couple “Viral code overloads one cache shard” to URL Create API. | Costs invalidation, staleness, stampede protection, and memory. Add or split it only after the workload (120K peak redirects/s · 6B links · p99 < 100 ms) proves repeated reads dominate. Measure the latency, saturation, lag, or mismatch at the Redis Cache boundary before extracting or scaling it. |
| Short-Code Router | Owns one bounded domain decision, transition, or operational capability. In this design it participates in: Reserve a numeric ID range locally, allocate one ID, and Base62 encode it. | Separates a distinct scale, ownership, policy, or failure boundary. It prevents Redis Cache from also owning the contract and failure behavior of Metadata Shards. | Keep this behavior inside an adjacent service. Prefer that simpler option until independent scale, ownership, policy, or failure isolation is measurable. Here that simpler choice would couple “Client times out after alias commit” to Redis Cache. | Costs an interface, deployment, telemetry, ownership, and failure mode. Keep it in-process first; extract when independent scale or reliability pays for the boundary. Measure the latency, saturation, lag, or mismatch at the Short-Code Router boundary before extracting or scaling it. |
| Metadata Shards | Owns one bounded domain decision, transition, or operational capability. In this design it participates in: Conditionally insert code→URL; custom aliases use a uniqueness constraint. | Separates a distinct scale, ownership, policy, or failure boundary. It prevents Short-Code Router from also owning the contract and failure behavior of Range ID Allocator. | Keep this behavior inside an adjacent service. Prefer that simpler option until independent scale, ownership, policy, or failure isolation is measurable. Here that simpler choice would couple “Editable destination races with cached redirect” to Short-Code Router. | Costs an interface, deployment, telemetry, ownership, and failure mode. Keep it in-process first; extract when independent scale or reliability pays for the boundary. Measure the latency, saturation, lag, or mismatch at the Metadata Shards boundary before extracting or scaling it. |
| Range ID Allocator | Owns one bounded domain decision, transition, or operational capability. In this design it participates in: On redirect, read edge/process cache, then Redis, then the owning metadata shard. | Separates a distinct scale, ownership, policy, or failure boundary. It prevents Metadata Shards from also owning the contract and failure behavior of Kafka Click Stream. | Keep this behavior inside an adjacent service. Prefer that simpler option until independent scale, ownership, policy, or failure isolation is measurable. Here that simpler choice would couple “ID worker loses its range lease” to Metadata Shards. | Costs an interface, deployment, telemetry, ownership, and failure mode. Keep it in-process first; extract when independent scale or reliability pays for the boundary. Measure the latency, saturation, lag, or mismatch at the Range ID Allocator boundary before extracting or scaling it. |
| Kafka Click Stream | Preserves durable ordering, replay, and consumer checkpoints. In this design it participates in: Return redirect immediately and publish a sampled/deduplicated click event asynchronously. | Decouples bursts and failure from user acknowledgment. It prevents Range ID Allocator from also owning the contract and failure behavior of Analytics Workers. | Call every downstream consumer synchronously. That couples user latency and availability to analytics, notification, indexing, and audit dependencies. Here that simpler choice would couple “Analytics lag grows without affecting redirects” to Range ID Allocator. | Costs eventual consistency, schema evolution, replay tooling, idempotent consumers, and lag operations. Earn it when bursts or downstream failure must not block acknowledgment. Measure the latency, saturation, lag, or mismatch at the Kafka Click Stream boundary before extracting or scaling it. |
| Analytics Workers | Executes idempotent asynchronous work under lease and retry policy. In this design it participates in: Validate and canonicalize the destination; run synchronous deny-list checks. | Separates a distinct scale, ownership, policy, or failure boundary. It prevents Kafka Click Stream from also owning the contract and failure behavior of OLAP Store. | Perform the work before acknowledging the caller. This gives simpler consistency but unbounded tail latency and fragile retries. Here that simpler choice would couple “Viral code overloads one cache shard” to Kafka Click Stream. | Costs leases, checkpoints, retries, DLQs, and lag operations. Separate once execution time or burstiness no longer fits the request deadline. Measure the latency, saturation, lag, or mismatch at the Analytics Workers boundary before extracting or scaling it. |
| OLAP Store | Owns authoritative versioned state or immutable evidence. In this design it participates in: Reserve a numeric ID range locally, allocate one ID, and Base62 encode it. | Defines the source of truth and commit boundary. It prevents Analytics Workers from also owning the contract and failure behavior of Abuse Scanner. | Let each service persist its own interpretation. That removes one clear commit boundary and makes retries, support, and reconciliation ambiguous. Here that simpler choice would couple “Client times out after alias commit” to Analytics Workers. | Costs schema migration, replication, backup, and shard ownership. Split storage only when access patterns, retention, or compliance boundaries materially differ. Measure the latency, saturation, lag, or mismatch at the OLAP Store boundary before extracting or scaling it. |
| Abuse Scanner | Owns one bounded domain decision, transition, or operational capability. In this design it participates in: Conditionally insert code→URL; custom aliases use a uniqueness constraint. | Separates a distinct scale, ownership, policy, or failure boundary. It prevents OLAP Store from also owning the contract and failure behavior of Config / SLOs. | Embed policy in every caller. Rules then drift by deployment version and emergency changes require fleet-wide redeployment. Here that simpler choice would couple “Editable destination races with cached redirect” to OLAP Store. | Costs an interface, deployment, telemetry, ownership, and failure mode. Keep it in-process first; extract when independent scale or reliability pays for the boundary. Measure the latency, saturation, lag, or mismatch at the Abuse Scanner boundary before extracting or scaling it. |
| Config / SLOs | Owns one bounded domain decision, transition, or operational capability. In this design it participates in: On redirect, read edge/process cache, then Redis, then the owning metadata shard. | Separates a distinct scale, ownership, policy, or failure boundary. It prevents Abuse Scanner from also owning the contract and failure behavior of operators and repair tooling. | Keep this behavior inside an adjacent service. Prefer that simpler option until independent scale, ownership, policy, or failure isolation is measurable. Here that simpler choice would couple “ID worker loses its range lease” to Abuse Scanner. | Costs an interface, deployment, telemetry, ownership, and failure mode. Keep it in-process first; extract when independent scale or reliability pays for the boundary. Measure the latency, saturation, lag, or mismatch at the Config / SLOs boundary before extracting or scaling it. |
Base62 is encoding, not uniqueness; lease numeric ranges or use Snowflake IDs.
A single deployable with one transactional store is the right starting point for a small url shortener workload. The proposed boundary becomes justified when base62 is encoding, not uniqueness; lease numeric ranges or use snowflake ids. Separating it contains the named failure “Viral code overloads one cache shard” without placing unrelated work on the critical path.
Use cache-aside reads, negative caching, TTL jitter, and request coalescing for viral links.
The design coordinates only where each accepted url shortener operation has one stable result and retries do not repeat its business effect. Everywhere else it accepts bounded staleness or asynchronous propagation. The alternative—strong coordination for every projection—simplifies the mental model but increases tail latency and turns partitions into broad write unavailability.
Partition by hash(short_code); keep click events off the redirect hot path.
This choice adds dashboards, ownership, schema compatibility, capacity planning, and recovery runbooks. Start with the minimum topology that supports “Conditionally insert code→URL; custom aliases use a uniqueness constraint.” and extract another service only when measured throughput, blast radius, data lifecycle, or team ownership changes independently.
Base62 is encoding, not uniqueness; lease numeric ranges or use Snowflake IDs.
Use cache-aside reads, negative caching, TTL jitter, and request coalescing for viral links.
Partition by hash(short_code); keep click events off the redirect hot path.
Validate and canonicalize the destination; run synchronous deny-list checks.
Reserve a numeric ID range locally, allocate one ID, and Base62 encode it.
Conditionally insert code→URL; custom aliases use a uniqueness constraint.
On redirect, read edge/process cache, then Redis, then the owning metadata shard.
Return redirect immediately and publish a sampled/deduplicated click event asynchronously.
identity = authenticate(request) prior = idempotency.get(identity, request.key) if prior: return prior.result current = authoritative_store.read(partition_key) next_state, events = domain.transition(current, request) authoritative_store.compare_and_set(current.version, next_state) idempotency.commit(request.key, next_state.result) outbox.append(events) return next_state.result
Cache immutable or slowly changing reads with versioned keys, TTL jitter, short negative entries, and request coalescing.
Measure per-key and per-tenant skew. Replicate safe reads, isolate the offender, salt only when ordering permits, and enforce budgets.
Bound queues, buffers, connection pools, and concurrency. Shed low-priority work and scale from lag/oldest-item age rather than CPU alone.
Use single-flight/coalescing, jittered expiry, bounded retries, exponential backoff, and circuit breakers so one dependency failure does not multiply traffic.
partition = stable_hash(primary_or_aggregate_key) → shard owner write = conditional_update(expected_version) read_projection = versioned and rebuildable
each accepted url shortener operation has one stable result and retries do not repeat its business effect. Use a uniqueness constraint, serializable/conditional write, expected version, or fencing token at this boundary.
Analytics, notifications, search, read models, and operational dashboards may lag when freshness is observable and replay exists.
| Operation | Consistency | Reason |
|---|---|---|
| Authoritative mutation | Conditional / serializable | Protect uniqueness, ownership, money, inventory, order, or legal state transition. |
| Read after own write | Primary, session token, or cache warm | The caller must observe the result it just committed. |
| Ordinary read projection | Bounded stale where safe | Replicas and caches improve latency when version/freshness is visible. |
| Analytics and operations | Eventual + replay | Freshness is less important than isolating the online path. |
| Failure | Runtime behavior | Recovery proof |
|---|---|---|
| Viral code overloads one cache shard | Isolate the key/tenant/priority, apply admission control, and preserve durable work. | Reconciliation returns zero invariant gaps; lag/replica health and user-visible SLO return to baseline. |
| Client times out after alias commit | Stop unsafe progress, serve only explicitly safe degraded behavior, and recover from durable state. | Reconciliation returns zero invariant gaps; lag/replica health and user-visible SLO return to baseline. |
| Editable destination races with cached redirect | Resolve at source of truth with uniqueness, expected version, lease generation, or monotonic cursor. | Reconciliation returns zero invariant gaps; lag/replica health and user-visible SLO return to baseline. |
| ID worker loses its range lease | Stop unsafe progress, serve only explicitly safe degraded behavior, and recover from durable state. | Reconciliation returns zero invariant gaps; lag/replica health and user-visible SLO return to baseline. |
| Analytics lag grows without affecting redirects | Stop unsafe progress, serve only explicitly safe degraded behavior, and recover from durable state. | Reconciliation returns zero invariant gaps; lag/replica health and user-visible SLO return to baseline. |
# Recovery checkpoint scenario: Viral code overloads one cache shard operation_id: op_01J... aggregate_key: url-shortener_123 last_durable_version: 18 projection_checkpoint: partition-07@offset-482901 retry_policy: same_identity / bounded_backoff reconciliation_status: pending owner: Config / SLOs
Every dependency needs a timeout, retry budget, circuit policy, and explicit fail-open, fail-closed, stale, or read-only mode. “Highly available” is incomplete until degraded behavior is named.
↑ topBase62 is encoding, not uniqueness; lease numeric ranges or use Snowflake IDs. Walk the concrete lifecycle step “Validate and canonicalize the destination; run synchronous deny-list checks.” Then test it against “Viral code overloads one cache shard”. State the retry identity, durable checkpoint, recovery signal, and cost of the alternative.
Use cache-aside reads, negative caching, TTL jitter, and request coalescing for viral links. Walk the concrete lifecycle step “Reserve a numeric ID range locally, allocate one ID, and Base62 encode it.” Then test it against “Client times out after alias commit”. State the retry identity, durable checkpoint, recovery signal, and cost of the alternative.
Partition by hash(short_code); keep click events off the redirect hot path. Walk the concrete lifecycle step “Conditionally insert code→URL; custom aliases use a uniqueness constraint.” Then test it against “Editable destination races with cached redirect”. State the retry identity, durable checkpoint, recovery signal, and cost of the alternative.
Base62 is encoding, not uniqueness; lease numeric ranges or use Snowflake IDs. Walk the concrete lifecycle step “On redirect, read edge/process cache, then Redis, then the owning metadata shard.” Then test it against “ID worker loses its range lease”. State the retry identity, durable checkpoint, recovery signal, and cost of the alternative.
Use cache-aside reads, negative caching, TTL jitter, and request coalescing for viral links. Walk the concrete lifecycle step “Return redirect immediately and publish a sampled/deduplicated click event asynchronously.” Then test it against “Analytics lag grows without affecting redirects”. State the retry identity, durable checkpoint, recovery signal, and cost of the alternative.
| Time | What to cover |
|---|---|
| 0–5 min | Clarify scope, workload, SLOs, and the correctness invariant. |
| 5–10 min | Estimate throughput/storage and define concrete APIs and records. |
| 10–20 min | Draw online, durable-write, and asynchronous/repair paths. |
| 20–30 min | Explain the exact lifecycle, partition key, and concurrency control. |
| 30–38 min | Discuss caching, hot keys, replication, and backpressure. |
| 38–43 min | Run failure drills, security, observability, and regional evolution. |
| 43–45 min | Summarize the five most important choices and trade-offs. |
| Invariant | each accepted url shortener operation has one stable result and retries do not repeat its business effect. |
|---|---|
| Partitioning | Stable aggregate/key hash with versioned ownership and measured hot-key isolation. |
| Commit | Expected version or uniqueness at the authoritative state boundary. |
| Async work | Durable outbox/log, idempotent consumers, checkpoints, and replay. |
| Recovery | Same operation identity, durable truth lookup, and business reconciliation. |