Requirements

Functional Requirements:

• The system shall allow a user to submit a long URL and receive a shortened URL (short code + domain).​​

• When a short URL is requested, the system shall redirect the client to the corresponding original long URL using an HTTP redirect (e.g., 301/302).​​

• The system shall allow a user to provide a custom short code (alias) if it is available and meets validation rules.​

• The system should generate a single urls if two users ask for the same url.

• For free users the system should only support main domains and not user search criteria. But for paid users will allow deeper parameters.

• The system shall allow a user to set an expiration time/date for a short URL, after which the redirect shall no longer work.

• The system shall provide an endpoint to retrieve metadata for a shortURL(original URL, created date, expiration, click count)

• The system should avoid spam urls for example changing the query parameters to generate different query parameters.

• The system should find a way to fingerprint the destination to check for abuse in de destination.

• The system should prevent IP registration.

• The system should save records from the user like geographical area and Ips address to link who generate the url with the url itself.

• The system should have a rate limiters to avoid attacks to the sources when generates an url.

Non-Functional Requirements:

Availability​

The service should be highly available (e.g., 99.9% uptime) so redirects work reliably.​

Performance / Latency​

Redirect requests should be fast (e.g., p95 < 50–100 ms at the edge/app layer,

excluding network conditions).​

Scalability​The system should scale horizontally to handle growth in both redirect traffic and new

URL creation.​

Reliability & Durability​

Stored mappings between short codes and long URLs should be durable (data should

not be lost after creation).​

Security​

The system should protect against common threats (injection, SSRF patterns, open

redirect abuse), support HTTPS, and sanitize/validate input.​

Observability​

The system should provide logs, metrics, and tracing (e.g., request rate, error rate

,latency, redirect counts) and alerting on anomalies.​

Maintainability​

The codebase should be modular and testable, with clear API contracts and

automated tests for core flows.​

Cost Efficiency​

The system should optimize for low cost per redirect (caching, efficientstorage/lookup,

minimal write amplification).​

Compatibility​

The service should work across common clients/browsers and handle typical URL

lengths and characters safely (proper encoding/decoding).​

API Design

URL Management​

POST /links​

Create a short URL from a long URL (supports custom alias, expiration, and duplicate handling).​

GET /links/{code}​

Retrieve metadata for a short URL (original URL, creation date, expiration, click count)​

Get /{userID}/bookmarks

​Retrieve the bookmarks from a specific users, like based on categories like "social"

Redirection​

GET /{code} (public short domain)​

Redirect the client to the original long URL if the short code exists and is not expired.​

(Optional / Supporting)​

GET /aliases/{alias}/availability​

Check if a custom alias is available before creating a short URL.​

High-Level Design

Users / Clients​

Create short URLs and access short links for redirection.​

Load Balancer​

Routes and distributes incoming traffic to the backend services.​

URL Shortening API (Management Service)​

Creates short URLs, validates input, applies duplicate strategy, supports custom aliases and expiration, generates unique identifiers (unique ID → Base62), and stores mappings in the database.​

Redirect Service (Read Path Service)​

Handles GET /{code} by resolving the short code to the long URL and returning an HTTP redirect (301/302).​ (needs to have more replicas to be tolerant to failures, maybe geographical but the creation can be single point failure).

Cache (e.g., Redis)​

Accelerates the read path by storing hot short_code → long_url mappings so most redirects are served without database access; updated on cache misses after a DB lookup.​

Database​

Persists URL mappings and metadata (created time, expiration, click count) and enforces uniqueness via a unique constraint/index on short_code to prevent collisions (including race conditions and custom aliases).