Requirements

Functional Requirements:

• Create a short URL for a given long URL.
• Return the long URL associated with a given short URL.

Non-Functional Requirements:

• low latency
  • 95% request must complete in > 2s
• scalability
  • the system can growth over time if traffic increased in 50%
• hight availability 99.9%

API Design

API Server have only two http/2 API handlers

The first one is - /create (creating an url)

Request:

• long-url: text
• expired-at: datetime (optional)

Response:

• short-url: text
• expired-at: datetime (as default N days, for data retention)

The second one is - /receive (return the long URL associated with short url)

Request:

• short-url: text

Response:

• long-url: text

When you are call /receive handler, you are forwarding to a target site, by redirection

High-Level Design

The system is a scalable URL shortening service designed for high read throughput and horizontal scalability

Request Flow

1. Client (browser or mobile app) sends an HTTP request.
2. Request passes through Cloudflare for:
   • DDoS protection
   • Rate limiting
   • Basic validation
3. Request is routed via AWS Load Balancer to an closest by location and available API Server
4. API Server validates the request and publishes an asynchronous message to a message broker.
5. Stateless workers consume messages from the broker and process them.
6. Data is stored in:

• A persistent database (source of truth).
• Redis (low-latency cache)

Key Architectural Characteristics

• Stateless API and workers → horizontal scalability.
• Asynchronous processing → decouples ingestion from execution
• AWS Load Balancing -> find closed by location server and route a traffic to a health API Server
• Redis cache → low-latency read path
• Persistent DB → durability and consistency
• Partitioned message broker → parallel processing

Scalability Model

• API servers scale horizontally
• Workers scale based on broker partitions
• Redis handles read-heavy traffic
• Database handles durable writes

Low-latency model

• Short URL stored via in-memory database
• Client request forwarding by load balancer to a nearest API Server

Hight availability

• all short URL's stored in persistent database with active sync replication
• all applications located in Kubernetes cluster
• if one of the workers down kubernetes cluster create a new pod with worker
• worker read only assigned partition

Detailed Component Design

1. API Layer

Role

• Validate requests.
• Publish asynchronous messages to the broker.
• Stateless — no direct DB interaction.

Scaling

• Horizontally scalable behind Load Balancer.
• Broker absorbs traffic spikes.

Trade-off

• Introduces eventual consistency due to async processing.

2. Message Broker

Role

• Buffers incoming requests
• Ensures durability
• Preserves order within partitions

Scaling

• Parallelism defined by number of partitions.
• Workers scale horizontally per partition.

3. Worker Layer

Workers consume messages and process:

• create requests
• receive requests

Stateless and horizontally scalable.

4. Create Flow

1. Generate short link ID.
2. Persist mapping in database (source of truth).
3. Write mapping to Redis for low-latency access.

Trade-offs

• Dual write (DB + Redis).
• Temporary inconsistency possible if cache write fails.

5. Receive Flow

1. Check Redis.
2. If miss → query DB.
3. If found → return result (optionally repopulate cache).
4. If not found → return 404

Pattern

• Cache-aside.
• Redis handles high read load.

Capacity Notes

• Broker partitions define processing parallelism.
• Redis handles read-heavy workload.
• Database handles durable writes and cache misses.