# buvanvarun/url-shortener architecture

> Architecture diagram of the GitHub repository buvanvarun/url-shortener, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/buvanvarun/url-shortener
- Repository: https://github.com/buvanvarun/url-shortener
- Video tour (about a minute): https://gitdiagram.com/buvanvarun/url-shortener/video

## Overview

This is a Spring Boot URL-shortening API. Users can register or log in, create links with generated or custom codes, follow redirects, manage owned links, and inspect click analytics. The main path runs from HTTP controllers through services to PostgreSQL and Redis; redirect resolution also records clicks asynchronously. The README documents shared Redis-backed rate limits and JWT ownership. Analytics implementation files and several configuration classes were not sampled, so their internal links are left unverified where source evidence is unavailable.

Main entry points: [`src/main/java/com/buvanvarun/urlshortener/service/UrlService.java`](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/service/UrlService.java) (URL service), [`src/main/java/com/buvanvarun/urlshortener/repository/UrlRepository.java`](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/repository/UrlRepository.java) (URL repository), [`src/main/java/com/buvanvarun/urlshortener/ratelimit/RateLimitFilter.java`](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/ratelimit/RateLimitFilter.java) (Rate limit filter), [`src/main/java/com/buvanvarun/urlshortener/service/AuthService.java`](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/service/AuthService.java) (Auth service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and redirects"]
  node_url_api["URL API<br/>[UrlController.java]"]
  node_redirect_api["Redirect endpoint"]
  node_error_handler["Error responses"]
end

subgraph group_identity["Identity and limits"]
  node_auth_api["Auth API"]
  node_auth_service["Auth service<br/>[AuthService.java]"]
  node_jwt["JWT service<br/>[JwtService.java]"]
  node_jwt_filter["JWT filter"]
  node_rate_filter["Rate limit filter"]
  node_bucket["Bucket resolver"]
  node_rate_config["Rate limit settings"]
  node_user_repo["User repository"]
end

subgraph group_links["Link management"]
  node_url_service["URL service<br/>[UrlService.java]"]
  node_code_generator["Code generator"]
  node_url_cache["URL cache"]
  node_cache_entry["Cache entry<br/>[UrlCacheEntry.java]"]
  node_url_repo["URL repository<br/>[UrlRepository.java]"]
end

subgraph group_analytics["Click analytics"]
  node_analytics_api["Analytics API"]
  node_analytics_service["Analytics service"]
  node_click_tracking["Click tracking"]
  node_click_repo["Click repository"]
end

node_user(("API user"))
node_postgres[("PostgreSQL")]
node_redis[("Redis")]

node_user -->|"registers or logs in"| node_auth_api
node_auth_api -->|"delegates to"| node_auth_service
node_auth_service -->|"reads and saves"| node_user_repo
node_auth_service -->|"issues token"| node_jwt
node_user -->|"creates and manages links"| node_url_api
node_url_api -->|"delegates to"| node_url_service
node_url_service -->|"requests codes"| node_code_generator
node_code_generator -->|"gets sequence ID"| node_url_repo
node_url_service -->|"reads and writes links"| node_url_repo
node_url_repo -.->|"persists link data"| node_postgres
node_url_service -->|"looks up, caches, evicts"| node_url_cache
node_url_cache -->|"stores entries"| node_cache_entry
node_url_cache -->|"reads and writes"| node_redis
node_user -->|"follows short link"| node_redirect_api
node_redirect_api -->|"resolves code"| node_url_service
node_url_service -->|"records click asynchronously"| node_click_tracking
node_click_tracking -->|"saves click event"| node_click_repo
node_click_tracking -->|"increments click count"| node_url_repo
node_click_repo -.->|"stores events"| node_postgres
node_user -->|"requests analytics"| node_analytics_api
node_analytics_api -.->|"delegates to"| node_analytics_service
node_analytics_service -.->|"queries click metrics"| node_click_repo
node_jwt_filter -->|"parses token"| node_jwt
node_rate_filter -->|"resolves bucket"| node_bucket
node_rate_filter -->|"uses limits"| node_rate_config
node_rate_filter -.->|"shares limit state"| node_redis
node_error_handler -.->|"returns API errors"| node_user

click node_url_api "https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/controller/UrlController.java"
click node_redirect_api "https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/controller/RedirectController.java"
click node_auth_api "https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/controller/AuthController.java"
click node_auth_service "https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/service/AuthService.java"
click node_jwt "https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/security/JwtService.java"
click node_jwt_filter "https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/security/JwtAuthenticationFilter.java"
click node_rate_filter "https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/ratelimit/RateLimitFilter.java"
click node_bucket "https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/ratelimit/BucketResolver.java"
click node_rate_config "https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/config/RateLimitProperties.java"
click node_url_service "https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/service/UrlService.java"
click node_code_generator "https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/service/ShortCodeGeneratorService.java"
click node_url_cache "https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/service/UrlCacheService.java"
click node_cache_entry "https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/service/UrlCacheEntry.java"
click node_url_repo "https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/repository/UrlRepository.java"
click node_user_repo "https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/repository/UserRepository.java"
click node_analytics_api "https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/controller/AnalyticsController.java"
click node_analytics_service "https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/service/AnalyticsService.java"
click node_click_tracking "https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/service/ClickTrackingService.java"
click node_click_repo "https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/repository/ClickEventRepository.java"
click node_error_handler "https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/exception/GlobalExceptionHandler.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_url_api,node_redirect_api,node_error_handler,node_user toneBlue
class node_auth_api,node_auth_service,node_jwt,node_jwt_filter,node_rate_filter,node_bucket,node_rate_config,node_user_repo,node_postgres,node_redis toneAmber
class node_url_service,node_code_generator,node_url_cache,node_cache_entry,node_url_repo toneMint
class node_analytics_api,node_analytics_service,node_click_tracking,node_click_repo toneRose
```

## Components

### API and redirects

- [URL API](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/controller/UrlController.java): `src/main/java/com/buvanvarun/urlshortener/controller/UrlController.java`
- [Redirect endpoint](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/controller/RedirectController.java): `src/main/java/com/buvanvarun/urlshortener/controller/RedirectController.java`
- [Error responses](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/exception/GlobalExceptionHandler.java): `src/main/java/com/buvanvarun/urlshortener/exception/GlobalExceptionHandler.java`

### Identity and limits

- [Auth API](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/controller/AuthController.java): `src/main/java/com/buvanvarun/urlshortener/controller/AuthController.java`
- [Auth service](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/service/AuthService.java): `src/main/java/com/buvanvarun/urlshortener/service/AuthService.java`
- [JWT service](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/security/JwtService.java): `src/main/java/com/buvanvarun/urlshortener/security/JwtService.java`
- [JWT filter](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/security/JwtAuthenticationFilter.java): `src/main/java/com/buvanvarun/urlshortener/security/JwtAuthenticationFilter.java`
- [Rate limit filter](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/ratelimit/RateLimitFilter.java): `src/main/java/com/buvanvarun/urlshortener/ratelimit/RateLimitFilter.java`
- [Bucket resolver](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/ratelimit/BucketResolver.java): `src/main/java/com/buvanvarun/urlshortener/ratelimit/BucketResolver.java`
- [Rate limit settings](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/config/RateLimitProperties.java): `src/main/java/com/buvanvarun/urlshortener/config/RateLimitProperties.java`
- [User repository](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/repository/UserRepository.java): `src/main/java/com/buvanvarun/urlshortener/repository/UserRepository.java`

### Link management

- [URL service](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/service/UrlService.java): `src/main/java/com/buvanvarun/urlshortener/service/UrlService.java`
- [Code generator](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/service/ShortCodeGeneratorService.java): `src/main/java/com/buvanvarun/urlshortener/service/ShortCodeGeneratorService.java`
- [URL cache](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/service/UrlCacheService.java): `src/main/java/com/buvanvarun/urlshortener/service/UrlCacheService.java`
- [Cache entry](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/service/UrlCacheEntry.java): `src/main/java/com/buvanvarun/urlshortener/service/UrlCacheEntry.java`
- [URL repository](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/repository/UrlRepository.java): `src/main/java/com/buvanvarun/urlshortener/repository/UrlRepository.java`

### Click analytics

- [Analytics API](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/controller/AnalyticsController.java): `src/main/java/com/buvanvarun/urlshortener/controller/AnalyticsController.java`
- [Analytics service](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/service/AnalyticsService.java): `src/main/java/com/buvanvarun/urlshortener/service/AnalyticsService.java`
- [Click tracking](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/service/ClickTrackingService.java): `src/main/java/com/buvanvarun/urlshortener/service/ClickTrackingService.java`
- [Click repository](https://github.com/buvanvarun/url-shortener/blob/main/src/main/java/com/buvanvarun/urlshortener/repository/ClickEventRepository.java): `src/main/java/com/buvanvarun/urlshortener/repository/ClickEventRepository.java`

### Other components

- **API user**
- **PostgreSQL**
- **Redis**

## Connections

- API user → Auth API: registers or logs in (evidence: `README.md`)
- Auth API → Auth service: delegates to (evidence: `src/main/java/com/buvanvarun/urlshortener/controller/AuthController.java`)
- Auth service → User repository: reads and saves (evidence: `src/main/java/com/buvanvarun/urlshortener/service/AuthService.java`)
- Auth service → JWT service: issues token (evidence: `src/main/java/com/buvanvarun/urlshortener/service/AuthService.java`)
- API user → URL API: creates and manages links (evidence: `README.md`)
- URL API → URL service: delegates to (evidence: `src/main/java/com/buvanvarun/urlshortener/controller/UrlController.java`)
- URL service → Code generator: requests codes (evidence: `src/main/java/com/buvanvarun/urlshortener/service/UrlService.java`)
- Code generator → URL repository: gets sequence ID (evidence: `src/main/java/com/buvanvarun/urlshortener/service/ShortCodeGeneratorService.java`)
- URL service → URL repository: reads and writes links (evidence: `src/main/java/com/buvanvarun/urlshortener/service/UrlService.java`)
- URL repository → PostgreSQL: persists link data (evidence: `README.md`)
- URL service → URL cache: looks up, caches, evicts (evidence: `src/main/java/com/buvanvarun/urlshortener/service/UrlService.java`)
- URL cache → Cache entry: stores entries (evidence: `src/main/java/com/buvanvarun/urlshortener/service/UrlCacheService.java`)
- URL cache → Redis: reads and writes (evidence: `README.md`)
- API user → Redirect endpoint: follows short link (evidence: `README.md`)
- Redirect endpoint → URL service: resolves code (evidence: `src/main/java/com/buvanvarun/urlshortener/controller/RedirectController.java`)
- URL service → Click tracking: records click asynchronously (evidence: `src/main/java/com/buvanvarun/urlshortener/service/UrlService.java`)
- Click tracking → Click repository: saves click event (evidence: `src/main/java/com/buvanvarun/urlshortener/service/ClickTrackingService.java`)
- Click tracking → URL repository: increments click count (evidence: `src/main/java/com/buvanvarun/urlshortener/service/ClickTrackingService.java`)
- Click repository → PostgreSQL: stores events (evidence: `README.md`)
- API user → Analytics API: requests analytics (evidence: `README.md`)
- Analytics API → Analytics service: delegates to (evidence: `src/main/java/com/buvanvarun/urlshortener/controller/AnalyticsController.java`)
- Analytics service → Click repository: queries click metrics (evidence: `src/main/java/com/buvanvarun/urlshortener/service/AnalyticsService.java`)
- JWT filter → JWT service: parses token (evidence: `src/main/java/com/buvanvarun/urlshortener/security/JwtAuthenticationFilter.java`)
- Rate limit filter → Bucket resolver: resolves bucket (evidence: `src/main/java/com/buvanvarun/urlshortener/ratelimit/RateLimitFilter.java`)
- Rate limit filter → Rate limit settings: uses limits (evidence: `src/main/java/com/buvanvarun/urlshortener/ratelimit/RateLimitFilter.java`)
- Rate limit filter → Redis: shares limit state (evidence: `README.md`)
- Error responses → API user: returns API errors (evidence: `src/main/java/com/buvanvarun/urlshortener/exception/GlobalExceptionHandler.java`)
