Skip to content

🔗 URL Shortener System Architecture

📋 Overview

System Purpose

A scalable URL shortening service that converts long URLs into short, manageable links while providing analytics and user management capabilities.

🖼️ Architecture Diagrams

Standard PlantUML View

FrontendBackendDatabaseCacheWeb ApplicationMobile AppAdmin DashboardAPI GatewayURL ServiceUser ServiceAnalytics ServiceRate LimiterURL RepositoryUser RepositoryAnalytics RepositoryRedis ClusterHandles authentication,request routing, andrate limitingStores frequently accessed URLsto reduce database load andimprove redirection performanceCore service for URL shorteningand redirection operationsTracks and processes URL usagemetrics and user interactions
522.

C4 Architecture Model

URL Shortening System[System]Frontend[Container]Backend[Container]Database[Container]Cache[Container]«container»Web Application«container»Mobile App«container»Admin Dashboard«container»API Gateway«container»URL Service«container»User Service«container»Analytics Service«container»Rate Limiter«container»URL Repository«container»User Repository«container»Analytics Repository«container»Redis ClusterHandles authentication,request routing, andrate limitingStores frequently accessedURLsto reduce database load andimprove redirectionperformanceCore service for URLshorteningand redirection operationsTracks and processes URLusagemetrics and user interactions............
URL Shortening System[System]Frontend[Container]Backend[Container]Database[Container]Cache[Container]«container»Web Application«container»Mobile App«container»Admin Dashboard«container»API Gateway«container»URL Service«container»User Service«container»Analytics Service«container»Rate Limiter«container»URL Repository«container»User Repository«container»Analytics Repository«container»Redis ClusterHandles authentication,request routing, andrate limitingStores frequently accessedURLsto reduce database load andimprove redirectionperformanceCore service for URLshorteningand redirection operationsTracks and processes URLusagemetrics and user interactions............

🧩 System Components

🌐 Frontend

  • 📱Web Application: Browser-based interface for URL shortening and management
  • 📲Mobile Application: On-the-go URL creation and management
  • ⚙️Admin Dashboard: System monitoring, user management, and configuration

🖥️ Backend Services

  • 🚪API Gateway: Entry point for all client requests, handling authentication and routing
  • ✂️URL Service: Core business logic for shortening and redirecting URLs
  • 👤User Service: Manages user accounts, authentication, and permissions
  • 📊Analytics Service: Collects and processes usage statistics
  • 🛡️Rate Limiter: Prevents abuse by limiting request rates

💾 Data Storage

  • 🔗URL Repository: Stores URL mappings and metadata
  • 👥User Repository: Stores user account information
  • 📈Analytics Repository: Stores click events and metrics

⚡ Cache Layer

  • 🚀Redis Cluster: In-memory cache for high-speed URL lookups and counters

🛠️ Technology Stack

Recommended Technologies

  • Frontend: React.js/Next.js (web), React Native (mobile)
  • Backend: Java/Spring Boot or Node.js/Express
  • Database: PostgreSQL (primary storage), MongoDB (analytics)
  • Cache: Redis (for URL lookups and counters)
  • API Gateway: Spring Cloud Gateway or Kong
  • Monitoring: Prometheus, Grafana
  • Container Orchestration: Kubernetes

📈 Scalability & Performance

Key Strategies

  • Horizontally scalable microservices
  • Database sharding for URL repository
  • Read replicas for high-traffic queries
  • Redis cluster for distributed caching
  • CDN integration for global low-latency access
  • Asynchronous processing for analytics events
  • Content-based partitioning for analytics data

📈 System Metrics

Key Metrics

  • URL Shortening Rate: Number of URLs created per second
  • URL Redirection Rate: Number of URL redirects per second
  • Database Read Latency: Time taken to retrieve URLs from the database
  • Cache Hit Rate: Percentage of requests served from the cache

📝 Static Class Diagrams

URL-id: UUID-originalUrl: String-shortCode: String-creationDate: DateTime-expirationDate: DateTime-isActive: Boolean-userId: UUID-clickCount: Integer-lastAccessedDate: DateTime+getId(): UUID+getOriginalUrl(): String+getShortCode(): String+getCreationDate(): DateTime+getExpirationDate(): DateTime+isActive(): Boolean+getUserId(): UUID+getClickCount(): Integer+getLastAccessedDate(): DateTime+setExpirationDate(date: DateTime): void+setActive(active: Boolean): void+incrementClickCount(): void+updateLastAccessedDate(): voidUser-id: UUID-username: String-email: String-passwordHash: String-creationDate: DateTime-lastLoginDate: DateTime-role: UserRole-apiKey: String-isActive: Boolean+getId(): UUID+getUsername(): String+getEmail(): String+getCreationDate(): DateTime+getLastLoginDate(): DateTime+getRole(): UserRole+getApiKey(): String+isActive(): Boolean+setLastLoginDate(date: DateTime): void+setRole(role: UserRole): void+regenerateApiKey(): String+setActive(active: Boolean): void+verifyPassword(password: String): BooleanUserRoleSTANDARDPREMIUMADMINAnalytics-id: UUID-urlId: UUID-timestamp: DateTime-ipAddress: String-userAgent: String-referrer: String-country: String-device: String-browser: String+getId(): UUID+getUrlId(): UUID+getTimestamp(): DateTime+getIpAddress(): String+getUserAgent(): String+getReferrer(): String+getCountry(): String+getDevice(): String+getBrowser(): StringURLService-urlRepository: URLRepository-cacheService: CacheService-idGenerator: IdGenerator-analyticsService: AnalyticsService-configService: ConfigService+createShortUrl(originalUrl: String, userId: UUID, expirationDate: DateTime): URL+getOriginalUrl(shortCode: String): String+getUrlByShortCode(shortCode: String): URL+getUrlsByUser(userId: UUID, page: Integer, size: Integer): List<URL>+updateUrl(urlId: UUID, updatedUrl: URL): URL+deactivateUrl(urlId: UUID): void+bulkCreateUrls(urls: List<String>, userId: UUID): List<URL>+isUrlValid(url: String): Boolean+generateShortCode(): StringUserService-userRepository: UserRepository-passwordEncoder: PasswordEncoder-emailService: EmailService-configService: ConfigService+createUser(user: User): User+authenticateUser(username: String, password: String): AuthToken+getUserById(userId: UUID): User+updateUser(userId: UUID, updatedUser: User): User+deactivateUser(userId: UUID): void+regenerateApiKey(userId: UUID): String+upgradeUserRole(userId: UUID, newRole: UserRole): void+validateApiKey(apiKey: String): BooleanAnalyticsService-analyticsRepository: AnalyticsRepository-urlRepository: URLRepository-geoLocationService: GeoLocationService-userAgentParserService: UserAgentParserService-cacheService: CacheService+recordClick(shortCode: String, requestInfo: RequestInfo): void+getClicksByUrl(urlId: UUID, timeRange: TimeRange): ClickStats+getClicksByUser(userId: UUID, timeRange: TimeRange): UserClickStats+generateDailyReport(userId: UUID): Report+getTopPerformingUrls(userId: UUID, limit: Integer): List<URL>+getReferrers(urlId: UUID): Map<String, Integer>+getGeographicDistribution(urlId: UUID): Map<String, Integer>+getDeviceDistribution(urlId: UUID): Map<String, Integer>creates10..*generates10..*has11
URL-id: UUID-originalUrl: String-shortCode: String-creationDate: DateTime-expirationDate: DateTime-isActive: Boolean-userId: UUID-clickCount: Integer-lastAccessedDate: DateTime+getId(): UUID+getOriginalUrl(): String+getShortCode(): String+getCreationDate(): DateTime+getExpirationDate(): DateTime+isActive(): Boolean+getUserId(): UUID+getClickCount(): Integer+getLastAccessedDate(): DateTime+setExpirationDate(date: DateTime): void+setActive(active: Boolean): void+incrementClickCount(): void+updateLastAccessedDate(): voidUser-id: UUID-username: String-email: String-passwordHash: String-creationDate: DateTime-lastLoginDate: DateTime-role: UserRole-apiKey: String-isActive: Boolean+getId(): UUID+getUsername(): String+getEmail(): String+getCreationDate(): DateTime+getLastLoginDate(): DateTime+getRole(): UserRole+getApiKey(): String+isActive(): Boolean+setLastLoginDate(date: DateTime): void+setRole(role: UserRole): void+regenerateApiKey(): String+setActive(active: Boolean): void+verifyPassword(password: String): BooleanUserRoleSTANDARDPREMIUMADMINAnalytics-id: UUID-urlId: UUID-timestamp: DateTime-ipAddress: String-userAgent: String-referrer: String-country: String-device: String-browser: String+getId(): UUID+getUrlId(): UUID+getTimestamp(): DateTime+getIpAddress(): String+getUserAgent(): String+getReferrer(): String+getCountry(): String+getDevice(): String+getBrowser(): StringURLService-urlRepository: URLRepository-cacheService: CacheService-idGenerator: IdGenerator-analyticsService: AnalyticsService-configService: ConfigService+createShortUrl(originalUrl: String, userId: UUID, expirationDate: DateTime): URL+getOriginalUrl(shortCode: String): String+getUrlByShortCode(shortCode: String): URL+getUrlsByUser(userId: UUID, page: Integer, size: Integer): List<URL>+updateUrl(urlId: UUID, updatedUrl: URL): URL+deactivateUrl(urlId: UUID): void+bulkCreateUrls(urls: List<String>, userId: UUID): List<URL>+isUrlValid(url: String): Boolean+generateShortCode(): StringUserService-userRepository: UserRepository-passwordEncoder: PasswordEncoder-emailService: EmailService-configService: ConfigService+createUser(user: User): User+authenticateUser(username: String, password: String): AuthToken+getUserById(userId: UUID): User+updateUser(userId: UUID, updatedUser: User): User+deactivateUser(userId: UUID): void+regenerateApiKey(userId: UUID): String+upgradeUserRole(userId: UUID, newRole: UserRole): void+validateApiKey(apiKey: String): BooleanAnalyticsService-analyticsRepository: AnalyticsRepository-urlRepository: URLRepository-geoLocationService: GeoLocationService-userAgentParserService: UserAgentParserService-cacheService: CacheService+recordClick(shortCode: String, requestInfo: RequestInfo): void+getClicksByUrl(urlId: UUID, timeRange: TimeRange): ClickStats+getClicksByUser(userId: UUID, timeRange: TimeRange): UserClickStats+generateDailyReport(userId: UUID): Report+getTopPerformingUrls(userId: UUID, limit: Integer): List<URL>+getReferrers(urlId: UUID): Map<String, Integer>+getGeographicDistribution(urlId: UUID): Map<String, Integer>+getDeviceDistribution(urlId: UUID): Map<String, Integer>creates10..*generates10..*has11

🔄 System Workflows

URL Shortening Process

ClientClientAPI GatewayAPI GatewayAuth ServiceAuth ServiceURL ServiceURL ServiceID GeneratorID GeneratorURL RepositoryURL RepositoryCache ServiceCache ServicePOST /api/urls {originalUrl, expirationDate}validateToken(token)Valid token + UserInfocreateShortUrl(originalUrl, userId, expirationDate)isUrlValid(originalUrl)generateShortCode()shortCodefindByShortCode(shortCode)Optional<URL>alt[shortCode already exists]generateShortCode()new shortCodesave(url)saved URLcacheUrl(url)confirmationURL entity201 Created + {shortUrl, expirationDate, ...}
ClientClientAPI GatewayAPI GatewayAuth ServiceAuth ServiceURL ServiceURL ServiceID GeneratorID GeneratorURL RepositoryURL RepositoryCache ServiceCache ServicePOST /api/urls {originalUrl, expirationDate}validateToken(token)Valid token + UserInfocreateShortUrl(originalUrl, userId, expirationDate)isUrlValid(originalUrl)generateShortCode()shortCodefindByShortCode(shortCode)Optional<URL>alt[shortCode already exists]generateShortCode()new shortCodesave(url)saved URLcacheUrl(url)confirmationURL entity201 Created + {shortUrl, expirationDate, ...}

URL Redirection Flow

ClientClientAPI GatewayAPI GatewayURL ServiceURL ServiceCache ServiceCache ServiceURL RepositoryURL RepositoryAnalytics ServiceAnalytics ServiceGET /{shortCode}getOriginalUrl(shortCode)getUrl(shortCode)Optional<URL>alt[URL not in cache]findByShortCode(shortCode)Optional<URL>alt[URL not found]URL not found404 Not Found[URL found but inactive]URL inactive410 Gone[URL found and active]update(url with incrementedClickCount)updated URLcacheUrl(url)confirmationoriginalUrl[URL in cache]incrementClickCount(shortCode)new countoriginalUrlrecordClick(shortCode, requestInfo)confirmation302 Redirect to originalUrl
ClientClientAPI GatewayAPI GatewayURL ServiceURL ServiceCache ServiceCache ServiceURL RepositoryURL RepositoryAnalytics ServiceAnalytics ServiceGET /{shortCode}getOriginalUrl(shortCode)getUrl(shortCode)Optional<URL>alt[URL not in cache]findByShortCode(shortCode)Optional<URL>alt[URL not found]URL not found404 Not Found[URL found but inactive]URL inactive410 Gone[URL found and active]update(url with incrementedClickCount)updated URLcacheUrl(url)confirmationoriginalUrl[URL in cache]incrementClickCount(shortCode)new countoriginalUrlrecordClick(shortCode, requestInfo)confirmation302 Redirect to originalUrl

Analytics Tracking

Client requests shortened URLAPI Gateway receives requestURL Service processes redirectionAnalytics Service receives click eventExtract request metadata (IP, User-Agent, Referrer)Determine geolocation from IPParse User-Agent for device/browser infoIncrement click counter for URLUpdate last accessed timestampCreate Analytics recordSave Analytics data to repositoryUpdate real-time metrics in cacheQueue for batch processingReturn redirection response to user
Client requests shortened URLAPI Gateway receives requestURL Service processes redirectionAnalytics Service receives click eventExtract request metadata (IP, User-Agent, Referrer)Determine geolocation from IPParse User-Agent for device/browser infoIncrement click counter for URLUpdate last accessed timestampCreate Analytics recordSave Analytics data to repositoryUpdate real-time metrics in cacheQueue for batch processingReturn redirection response to user

URL Lifecycle

CreatedActiveInactiveExpiredURL is created butnot yet active for useURL is accessible andredirects to original URLURL exists but redirectsto an inactive pageURL has reached itsexpiration dateURL is shortenedURL is publishedUser deactivates before publishingUser deactivates URLUser reactivates URLExpiration date reachedUser extends expirationURL is deletedURL is deletedURL is purged after grace period
522.

🗃️ Database Schema

usersidUUIDusername VARCHARemail VARCHARpassword_hash VARCHARcreation_date TIMESTAMPlast_login_date TIMESTAMProle VARCHARapi_key VARCHARis_active BOOLEANurlsidUUIDoriginal_url VARCHARshort_code VARCHARcreation_date TIMESTAMPexpiration_date TIMESTAMPis_active BOOLEANuser_idUUIDclick_count INTEGERlast_accessed_date TIMESTAMPanalyticsidUUIDurl_idUUIDtimestamp TIMESTAMPip_address VARCHARuser_agent VARCHARreferrer VARCHARcountry VARCHARdevice VARCHARbrowser VARCHARrate_limitsidUUIDuser_idUUIDendpoint VARCHARrequest_count INTEGERreset_time TIMESTAMPurl_metadataidUUIDurl_idUUIDtitle VARCHARdescription VARCHARthumbnail_url VARCHARlast_fetched TIMESTAMPcreates10..*generates10..*has10..*has10..1
usersidUUIDusername VARCHARemail VARCHARpassword_hash VARCHARcreation_date TIMESTAMPlast_login_date TIMESTAMProle VARCHARapi_key VARCHARis_active BOOLEANurlsidUUIDoriginal_url VARCHARshort_code VARCHARcreation_date TIMESTAMPexpiration_date TIMESTAMPis_active BOOLEANuser_idUUIDclick_count INTEGERlast_accessed_date TIMESTAMPanalyticsidUUIDurl_idUUIDtimestamp TIMESTAMPip_address VARCHARuser_agent VARCHARreferrer VARCHARcountry VARCHARdevice VARCHARbrowser VARCHARrate_limitsidUUIDuser_idUUIDendpoint VARCHARrequest_count INTEGERreset_time TIMESTAMPurl_metadataidUUIDurl_idUUIDtitle VARCHARdescription VARCHARthumbnail_url VARCHARlast_fetched TIMESTAMPcreates10..*generates10..*has10..*has10..1

🧠 Key Design Decisions

Technical Choices

  1. 🔤Short Code Generation: Custom base62 encoding algorithm for short, unique, readable codes
  2. 💨Cache Strategy: Multi-level caching with Redis for hot URLs to minimize database load
  3. 📊Analytics Processing: Asynchronous event processing to prevent impact on redirection performance
  4. 🗄️Database Partitioning: URLs partitioned by creation date for improved query performance
  5. 🔒Security Measures: Rate limiting, input validation, and output encoding to prevent abuse
  6. ⏱️URL Expiration: Configurable expiration policies with automatic cleanup for database management
  7. 📡Monitoring: Comprehensive metrics collection for system health and performance analysis
  8. 🏷️Custom Domain Support: Optional custom domain integration for branded short URLs