# ganeshedula/url_shorter architecture

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

- Interactive diagram: https://gitdiagram.com/ganeshedula/url_shorter
- Repository: https://github.com/ganeshedula/url_shorter

## Overview

This is a Spring Boot REST backend for account-authenticated URL shortening. Users register or sign in, manage owner-scoped short links, and resolve links through a redirect that records clicks; analytics summarize those events. Authentication also supports OTP verification and Google OAuth, while JWTs and Redis-backed sessions govern protected requests. The graph follows the documented capabilities and sampled controller/service/repository behavior; unsampled analytics enrichment and other wiring are represented only where directory and type names support it.

Main entry points: [`src/main/java/com/url/shortener/service/AuthService.java`](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/AuthService.java) (Auth workflows), [`src/main/java/com/url/shortener/service/UrlMappingService.java`](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/UrlMappingService.java) (URL workflows), [`src/main/java/com/url/shortener/service/GoogleOAuthService.java`](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/GoogleOAuthService.java) (Google OAuth), [`src/main/java/com/url/shortener/controllers/UrlMappingController.java`](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/controllers/UrlMappingController.java) (URL endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_auth["Identity and sessions"]
  node_auth_api["Auth endpoints"]
  node_auth_service["Auth workflows<br/>[AuthService.java]"]
  node_otp["OTP workflows<br/>[OtpService.java]"]
  node_google["Google OAuth"]
  node_user_service["User service<br/>[UserService.java]"]
  node_user_store[("User records")]
  node_email["Email delivery<br/>[EmailService.java]"]
  node_redis_sessions[("Redis sessions")]
end

subgraph group_urls["Short URL lifecycle"]
  node_url_api["URL endpoints"]
  node_client_info["Client metadata"]
  node_url_service["URL workflows"]
  node_codes["Code generator"]
  node_url_store[("URL records")]
end

subgraph group_analytics["Click analytics"]
  node_click_store[("Click records")]
  node_event["Click event"]
  node_enrichment["Click enrichment"]
  node_geo_service["Geo lookup"]
  node_geo_clients["GeoIP clients"]
end

subgraph group_runtime["Request security"]
  node_jwt["JWT service<br/>[JwtService.java]"]
  node_security["Security filters"]
  node_jwt_filter["JWT filter"]
  node_rate_filter["Rate limiting"]
end

node_client(("API client"))
node_email_provider["Brevo service"]
node_redis[("Redis")]
node_geo_provider["GeoIP provider"]
node_google_provider["Google identity"]

node_client -->|"calls auth API"| node_auth_api
node_client -->|"calls URL API"| node_url_api
node_auth_api -->|"delegates auth"| node_auth_service
node_auth_api -->|"starts OAuth"| node_google
node_auth_service -->|"issues/verifies OTP"| node_otp
node_auth_service -->|"creates/validates tokens"| node_jwt
node_auth_service -->|"manages sessions"| node_redis_sessions
node_auth_service -->|"uses users"| node_user_service
node_user_service -->|"reads/writes users"| node_user_store
node_otp -->|"stores OTP state"| node_redis
node_otp -->|"sends codes"| node_email
node_email -.->|"delivers mail"| node_email_provider
node_google -->|"uses OAuth state"| node_redis_sessions
node_google -->|"completes sign-in"| node_auth_service
node_google -.->|"exchanges/verifies"| node_google_provider
node_redis_sessions -->|"stores sessions"| node_redis
node_url_api -->|"delegates URLs"| node_url_service
node_url_api -->|"resolves owner"| node_user_service
node_url_api -->|"extracts click data"| node_client_info
node_url_service -->|"generates codes"| node_codes
node_url_service -->|"reads/writes URLs"| node_url_store
node_url_service -->|"records and queries clicks"| node_click_store
node_url_service -->|"publishes click event"| node_event
node_event -->|"dispatches event"| node_enrichment
node_enrichment -->|"enriches location"| node_geo_service
node_geo_service -->|"uses lookup clients"| node_geo_clients
node_geo_clients -.->|"queries location"| node_geo_provider
node_client -->|"sends protected request"| node_security
node_security -->|"configures filter"| node_jwt_filter
node_security -->|"configures filter"| node_rate_filter
node_jwt_filter -->|"validates bearer token"| node_jwt
node_jwt_filter -->|"checks revocation"| node_redis_sessions

click node_auth_api "https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/controllers/AuthController.java"
click node_auth_service "https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/AuthService.java"
click node_otp "https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/OtpService.java"
click node_google "https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/GoogleOAuthService.java"
click node_user_service "https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/UserService.java"
click node_user_store "https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/repo/UserRepository.java"
click node_email "https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/EmailService.java"
click node_jwt "https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/security/JwtService.java"
click node_redis_sessions "https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/RedisSessionService.java"
click node_url_api "https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/controllers/UrlMappingController.java"
click node_client_info "https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/util/ClientInfoExtractor.java"
click node_url_service "https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/UrlMappingService.java"
click node_codes "https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/util/ShortCodeGenerator.java"
click node_url_store "https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/repo/UrlMappingRepository.java"
click node_click_store "https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/repo/ClickEventRepository.java"
click node_event "https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/ClickEventRecorded.java"
click node_enrichment "https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/ClickAnalyticsEnrichmentListener.java"
click node_geo_service "https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/GeoLocationService.java"
click node_geo_clients "https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/GeoLocationClient.java"
click node_security "https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/security/security/WebSecurityConfig.java"
click node_jwt_filter "https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/security/JwtAuthenticationFilter.java"
click node_rate_filter "https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/security/RateLimitFilter.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_auth_api,node_auth_service,node_otp,node_google,node_user_service,node_user_store,node_email,node_redis_sessions,node_client toneBlue
class node_url_api,node_client_info,node_url_service,node_codes,node_url_store,node_redis toneAmber
class node_click_store,node_event,node_enrichment,node_geo_service,node_geo_clients toneMint
class node_jwt,node_security,node_jwt_filter,node_rate_filter toneRose
class node_email_provider,node_geo_provider,node_google_provider toneIndigo
```

## Components

### Identity and sessions

- [Auth endpoints](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/controllers/AuthController.java): `src/main/java/com/url/shortener/controllers/AuthController.java`
- [Auth workflows](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/AuthService.java): `src/main/java/com/url/shortener/service/AuthService.java`
- [OTP workflows](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/OtpService.java): `src/main/java/com/url/shortener/service/OtpService.java`
- [Google OAuth](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/GoogleOAuthService.java): `src/main/java/com/url/shortener/service/GoogleOAuthService.java`
- [User service](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/UserService.java): `src/main/java/com/url/shortener/service/UserService.java`
- [User records](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/repo/UserRepository.java): `src/main/java/com/url/shortener/repo/UserRepository.java`
- [Email delivery](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/EmailService.java): `src/main/java/com/url/shortener/service/EmailService.java`
- [Redis sessions](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/RedisSessionService.java): `src/main/java/com/url/shortener/service/RedisSessionService.java`

### Short URL lifecycle

- [URL endpoints](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/controllers/UrlMappingController.java): `src/main/java/com/url/shortener/controllers/UrlMappingController.java`
- [Client metadata](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/util/ClientInfoExtractor.java): `src/main/java/com/url/shortener/util/ClientInfoExtractor.java`
- [URL workflows](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/UrlMappingService.java): `src/main/java/com/url/shortener/service/UrlMappingService.java`
- [Code generator](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/util/ShortCodeGenerator.java): `src/main/java/com/url/shortener/util/ShortCodeGenerator.java`
- [URL records](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/repo/UrlMappingRepository.java): `src/main/java/com/url/shortener/repo/UrlMappingRepository.java`

### Click analytics

- [Click records](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/repo/ClickEventRepository.java): `src/main/java/com/url/shortener/repo/ClickEventRepository.java`
- [Click event](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/ClickEventRecorded.java): `src/main/java/com/url/shortener/service/ClickEventRecorded.java`
- [Click enrichment](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/ClickAnalyticsEnrichmentListener.java): `src/main/java/com/url/shortener/service/ClickAnalyticsEnrichmentListener.java`
- [Geo lookup](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/GeoLocationService.java): `src/main/java/com/url/shortener/service/GeoLocationService.java`
- [GeoIP clients](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/service/GeoLocationClient.java): `src/main/java/com/url/shortener/service/GeoLocationClient.java`

### Request security

- [JWT service](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/security/JwtService.java): `src/main/java/com/url/shortener/security/JwtService.java`
- [Security filters](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/security/security/WebSecurityConfig.java): `src/main/java/com/url/shortener/security/security/WebSecurityConfig.java`
- [JWT filter](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/security/JwtAuthenticationFilter.java): `src/main/java/com/url/shortener/security/JwtAuthenticationFilter.java`
- [Rate limiting](https://github.com/ganeshedula/url_shorter/blob/main/src/main/java/com/url/shortener/security/RateLimitFilter.java): `src/main/java/com/url/shortener/security/RateLimitFilter.java`

### Other components

- **API client**
- **Brevo service**
- **Redis**
- **GeoIP provider**
- **Google identity**

## Connections

- API client → Auth endpoints: calls auth API
- API client → URL endpoints: calls URL API
- Auth endpoints → Auth workflows: delegates auth
- Auth endpoints → Google OAuth: starts OAuth
- Auth workflows → OTP workflows: issues/verifies OTP
- Auth workflows → JWT service: creates/validates tokens
- Auth workflows → Redis sessions: manages sessions
- Auth workflows → User service: uses users
- User service → User records: reads/writes users
- OTP workflows → Redis: stores OTP state
- OTP workflows → Email delivery: sends codes
- Email delivery → Brevo service: delivers mail
- Google OAuth → Redis sessions: uses OAuth state
- Google OAuth → Auth workflows: completes sign-in
- Google OAuth → Google identity: exchanges/verifies
- Redis sessions → Redis: stores sessions
- URL endpoints → URL workflows: delegates URLs
- URL endpoints → User service: resolves owner
- URL endpoints → Client metadata: extracts click data
- URL workflows → Code generator: generates codes
- URL workflows → URL records: reads/writes URLs
- URL workflows → Click records: records and queries clicks
- URL workflows → Click event: publishes click event
- Click event → Click enrichment: dispatches event
- Click enrichment → Geo lookup: enriches location
- Geo lookup → GeoIP clients: uses lookup clients
- GeoIP clients → GeoIP provider: queries location
- API client → Security filters: sends protected request
- Security filters → JWT filter: configures filter
- Security filters → Rate limiting: configures filter
- JWT filter → JWT service: validates bearer token
- JWT filter → Redis sessions: checks revocation