URL Shortener Backend

Production-ready reactive URL shortener backend built with Java 17, Spring Boot WebFlux, PostgreSQL, and Redis.

Features

• Create short URLs from long URLs
• Custom alias support
• Expiring links with TTL
• Redirect support with cached hot URLs
• Click count and basic analytics
• In-memory rate limiting for URL creation
• Non-blocking APIs with Mono and reactive I/O
• Swagger/OpenAPI docs
• Unit and integration tests

Architecture

flowchart LR
    Client["Client / API Consumer"] --> API["Spring WebFlux API"]
    API --> Controller["Reactive Controllers"]
    Controller --> Service["Reactive Services"]
    Service --> Redis["Reactive Redis Cache"]
    Service --> DB["PostgreSQL via R2DBC"]
    Service --> Analytics["Reactive Click Tracking"]
    Analytics --> DB

Loading

API

Create short URL

• POST /api/shorten

{
  "originalUrl": "https://example.com/docs",
  "customAlias": "docs",
  "expiryDate": "2026-05-01T10:00:00"
}

Redirect

• GET /{shortCode}

Analytics

• GET /api/stats/{shortCode}

Swagger

• /swagger-ui.html

Running locally

./mvnw spring-boot:run

Make sure PostgreSQL and Redis are running locally before starting the app.

Default local configuration:

• PostgreSQL: r2dbc:postgresql://localhost:5432/url_shortener
• Username: postgres
• Password: postgres
• Redis host: localhost
• Redis port: 6379
• Base URL: http://localhost:8080

Scaling decisions

• PostgreSQL remains the system of record, accessed through R2DBC for non-blocking database operations.
• Redis caches hot redirects through the reactive Redis client to reduce database reads and improve latency.
• Short code generation uses Base62 with retry-on-collision and database uniqueness enforcement.
• Click tracking is recorded as a reactive flow so redirect requests stay non-blocking.
• Rate limiting is applied to URL creation endpoints to reduce abuse.
• The layered reactive design keeps controllers thin and business logic isolated for easier horizontal scaling.

Testing

./mvnw test