🔗 URL Shortener — System Design Study Project

A full-stack URL shortener built to learn and practice system design concepts hands-on. The project implements core distributed systems patterns — URL shortening with Base62 encoding, rate limiting with a sliding window algorithm, and round-robin load balancing — all in a clean Spring Boot + React stack.

---

Architecture Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                              BROWSER                                        │
│  ┌───────────────────────────────────────────────────────────┐              │
│  │  React Frontend (localhost:3000)                          │              │
│  │  ┌──────────────┐  ┌────────────┐  ┌───────────────────┐ │              │
│  │  │ ShorternForm │  │ ResultCard │  │   LinkHistory     │ │              │
│  │  └──────┬───────┘  └────────────┘  └───────────────────┘ │              │
│  │         │              ▲                    ▲             │              │
│  │         ▼              │                    │             │              │
│  │  ┌─────────────────────┴────────────────────┘             │              │
│  │  │            urlService.js (axios)                       │              │
│  │  │   POST /api/urls/shorten  GET /api/urls                │              │
│  │  └──────────────────────┬─────────────────────────────────┘              │
│  └─────────────────────────┼─────────────────────────────────┘              │
│                            │  CORS                                          │
└────────────────────────────┼────────────────────────────────────────────────┘
                             │
┌────────────────────────────┼────────────────────────────────────────────────┐
│  Spring Boot Backend (localhost:8080)                                        │
│                            │                                                │
│  ┌─────────────────────────▼──────────────────────────────────────────────┐ │
│  │                    RateLimiterInterceptor                              │ │
│  │           (Sliding Window — 5 req/min per IP)                         │ │
│  │             Returns HTTP 429 if limit exceeded                        │ │
│  └─────────────────────────┬──────────────────────────────────────────────┘ │
│                            │                                                │
│  ┌─────────────────────────▼──────────────────────────────────────────────┐ │
│  │                      UrlController                                    │ │
│  │  POST /api/urls/shorten  │  GET /api/urls  │  GET /{shortId} (302)    │ │
│  │  DELETE /api/urls/{id}   │                 │                          │ │
│  └─────────────────────────┬──────────────────────────────────────────────┘ │
│                            │                                                │
│  ┌─────────────────────────▼──────────────────────────────────────────────┐ │
│  │                       UrlService                                      │ │
│  │  shortenUrl()  │  getAllUrls()  │  getOriginalAndTrackClick()          │ │
│  │                │                │  (increments clickCount)             │ │
│  └────────┬───────┴────────────────┴──────────────────────────────────────┘ │
│           │                                                                 │
│  ┌────────▼─────────┐   ┌─────────────────┐                                │
│  │  Base62Util       │   │  UrlRepository  │                                │
│  │  (ID → shortCode) │   │  (JPA/SQLite)   │                                │
│  └──────────────────┘   └────────┬────────┘                                │
│                                  │                                          │
│  ┌───────────────────────────────▼────────────────────────────────────────┐ │
│  │                     SQLite (urlshortner.db)                            │ │
│  │  url_mapping: id | long_url | short_id | click_count | created_at     │ │
│  └───────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘

---

Tech Stack

Layer	Technology	Purpose
Frontend	React 19, Axios, Tailwind CSS	SPA for shortening URLs and viewing history
Backend	Spring Boot 4.0, Java 17	REST API, business logic, CORS handling
Database	SQLite (via JPA/Hibernate)	Persistent storage for URL mappings
Encoding	Base62 (custom utility)	Converts auto-increment DB IDs to short codes

---

System Design Concepts Implemented

1. URL Shortening (Base62 Encoding)

The core algorithm converts a database auto-increment ID into a short alphanumeric string:

ID = 1  →  encode(1)  →  "b"
ID = 62 →  encode(62) →  "ba"
ID = 238328 → encode(238328) → "bzzz"

Why Base62? — Uses a-z, A-Z, 0-9 (62 chars). A 7-character code supports 62⁷ = 3.5 trillion unique URLs. No special characters, so codes are URL-safe and copy-paste friendly.

Custom alias support — Users can optionally provide their own alias (e.g., my-site) instead of the auto-generated code.

2. Rate Limiting (Sliding Window)

Every incoming request passes through a RateLimiterInterceptor before reaching any controller:

Request → [RateLimiterInterceptor] → Allow? → Controller
                    │
                    ├─ Tracks timestamps per IP in a ConcurrentHashMap
                    ├─ Window: 60 seconds, Limit: 5 requests
                    └─ Exceeds? → HTTP 429 "Too Many Requests"

Algorithm: Sliding Window Log — stores exact request timestamps and removes expired ones on each check. Thread-safe via ConcurrentHashMap + Collections.synchronizedList.

3. Load Balancer (Round-Robin)

A simple round-robin load balancer distributes requests across multiple backend instances:

Request 1 → localhost:8081
Request 2 → localhost:8082
Request 3 → localhost:8083
Request 4 → localhost:8081  (cycles back)

Uses AtomicInteger for thread-safe index rotation.

4. CORS (Cross-Origin Resource Sharing)

Configured in CorsConfig.java to allow the React dev server (port 3000) to call the Spring Boot API (port 8080):

registry.addMapping("/**")
        .allowedOrigins("*")
        .allowedMethods("*");

---

API Endpoints

Method	Endpoint	Description	Request Body	Response
POST	/api/urls/shorten	Shorten a URL	{"originalUrl": "...", "alias": "..."}	UrlResponse JSON
GET	/api/urls	Get all shortened URLs	—	UrlResponse[]
DELETE	/api/urls/{id}	Delete a URL by ID	—	204 No Content
GET	/{shortId}	Redirect to original URL	—	302 Redirect

Response Shape (UrlResponse)

{
  "id": 1,
  "originalUrl": "https://google.com",
  "shortUrl": "http://localhost:8080/b",
  "shortCode": "b",
  "clickCount": 3,
  "createdAt": "2026-02-21T00:31:35.092"
}

---

Project Structure

SystemDesignURLShortner/
├── URLShortner/                          # Spring Boot Backend
│   └── src/main/java/com/systemdesig/
│       ├── SystemDesignApplication.java  # Entry point
│       ├── config/
│       │   ├── CorsConfig.java           # CORS policy
│       │   ├── WebConfig.java            # Interceptor registration
│       │   └── RateLimiterInterceptor.java # Pre-request rate check
│       ├── urlshortner/
│       │   ├── UrlController.java        # REST endpoints
│       │   ├── UrlService.java           # Business logic
│       │   ├── UrlRepository.java        # JPA data access
│       │   ├── UrlMapping.java           # Entity (DB table)
│       │   ├── ShortenRequest.java       # Request DTO
│       │   └── UrlResponse.java          # Response DTO
│       ├── ratelimiter/
│       │   ├── RateLimitController.java  # Rate limit test endpoint
│       │   └── RateLimiterService.java   # Sliding window algorithm
│       ├── loadbalancer/
│       │   ├── LoadBalancerController.java
│       │   └── LoadBalancerService.java  # Round-robin selector
│       └── common/util/
│           └── Base62Util.java           # ID → short code encoding
│
└── url_frontend/                         # React Frontend
    └── src/
        ├── App.jsx                       # Main app with history + form
        ├── api/urlService.js             # Axios HTTP client
        └── components/
            ├── ShorternForm.jsx          # URL input + shorten button
            ├── ResultCard.jsx            # Displays shortened URL + copy
            ├── LinkHistory.jsx           # Table of past shortened URLs
            └── Navbar.jsx                # Top navigation bar

---

Getting Started

Prerequisites

• Java 17+
• Maven 3.8+
• Node.js 18+

Run the Backend

cd URLShortner
mvn spring-boot:run
# Starts on http://localhost:8080

Run the Frontend

cd url_frontend
npm install
npm start
# Opens http://localhost:3000

Quick Test with curl

# Shorten a URL
curl -X POST http://localhost:8080/api/urls/shorten \
  -H "Content-Type: application/json" \
  -d '{"originalUrl":"https://github.com"}'

# Get history
curl http://localhost:8080/api/urls

# Test redirect (use the shortCode from the shorten response)
curl -v http://localhost:8080/b

---

Future Improvements Roadmap

Phase 1 — Production Database

Change	Why
Replace SQLite → PostgreSQL	SQLite doesn't support concurrent writes well; PSQL handles production workloads
Add Flyway migrations	Version-controlled schema changes instead of ddl-auto=update
Add connection pooling config	HikariCP tuning for production connection management

Phase 2 — Redis for Rate Limiting & Caching

Change	Why
Move rate limiter state to Redis	In-memory ConcurrentHashMap is lost on restart and doesn't work across multiple server instances
Use Redis SORTED SET for sliding window	ZADD + ZRANGEBYSCORE gives O(log n) sliding window with automatic expiry
Add Redis cache for hot short URLs	Avoid DB lookups for frequently accessed short codes; huge latency reduction
TTL-based cache eviction	Auto-expire cache entries for rarely used URLs

Phase 3 — Distributed System Patterns

Change	Why
Distributed ID generation (Twitter Snowflake / UUID)	Auto-increment IDs don't scale across multiple DB instances
Real load balancer (Nginx / Spring Cloud Gateway)	Replace the demo round-robin class with infrastructure-level load balancing
Multiple backend instances	Run 2-3 Spring Boot instances behind the load balancer
Database read replicas	Separate read traffic (redirects) from write traffic (shortening)

Phase 4 — Analytics & Monitoring

Change	Why
Click analytics dashboard	Track clicks by time, geography, referrer
Store click events in a time-series DB (InfluxDB / TimescaleDB)	Efficient storage for high-volume event data
Add Prometheus + Grafana monitoring	Track API latency, error rates, throughput
Structured logging (ELK stack)	Centralized log collection and searchability

Phase 5 — Security & Reliability

Change	Why
User authentication (JWT / OAuth2)	Associate URLs with user accounts
URL validation & sanitization	Block malicious URLs, validate format
Custom domain support	Let users use their own domain for short links
Expiry / TTL for short URLs	Auto-delete URLs after a configurable period
Restrict CORS to specific origins	allowedOrigins("*") is fine for dev, not for production

---

System Design Diagram (Scaled Version)

                    ┌──────────┐
                    │  Client  │
                    └────┬─────┘
                         │
                    ┌────▼─────┐
                    │  Nginx   │  (Load Balancer + SSL Termination)
                    └────┬─────┘
                         │
            ┌────────────┼────────────┐
            ▼            ▼            ▼
      ┌──────────┐ ┌──────────┐ ┌──────────┐
      │ App Srv 1│ │ App Srv 2│ │ App Srv 3│  (Spring Boot instances)
      └────┬─────┘ └────┬─────┘ └────┬─────┘
           │             │            │
           └─────────────┼────────────┘
                         │
              ┌──────────┼──────────┐
              ▼                     ▼
        ┌──────────┐         ┌──────────┐
        │  Redis   │         │ Postgres │
        │ (Cache + │         │ (Primary │
        │  Rate    │         │  + Read  │
        │  Limit)  │         │ Replicas)│
        └──────────┘         └──────────┘

---

Built for learning system design — one component at a time. 🚀