# shravya33/url-shortener-service architecture

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

- Interactive diagram: https://gitdiagram.com/shravya33/url-shortener-service
- Repository: https://github.com/shravya33/url-shortener-service

## Overview

This Spring Boot service accepts URL-shortening and analytics requests, persists mappings in MySQL, and redirects short-code visits while tracking clicks and enforcing expiration. The graph follows the sampled controller-to-service-to-repository calls; README-documented redirect and health endpoints are included. Some DTOs, utilities, and exception components are indexed but their implementation excerpts do not show all relationships, so those links are omitted where evidence is insufficient.

Main entry points: [`src/main/java/com/urlshortener/service/impl/UrlServiceImpl.java`](https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/service/impl/UrlServiceImpl.java) (URL service), [`src/main/java/com/urlshortener/controller/UrlController.java`](https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/controller/UrlController.java) (URL endpoints), [`src/main/java/com/urlshortener/exception/GlobalExceptionHandler.java`](https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/exception/GlobalExceptionHandler.java) (Error mapping), [`src/main/java/com/urlshortener/repository/UrlRepository.java`](https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/repository/UrlRepository.java) (URL repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_url_controller["URL endpoints<br/>[UrlController.java]"]
  node_redirect_controller["Redirect endpoint"]
  node_health_controller["Health check"]
  node_error_handler["Error mapping"]
  node_create_request["Create request"]
  node_short_response["Short URL response"]
  node_analytics_response["Analytics response"]
  node_error_response["Error response"]
end

subgraph group_domain["URL workflows"]
  node_url_service["URL service"]
  node_code_generator["Code generation"]
  node_reserved_aliases["Reserved aliases"]
end

subgraph group_persistence["Persistence and errors"]
  node_url_mapping["URL mapping<br/>[UrlMapping.java]"]
  node_url_repository["URL repository<br/>[UrlRepository.java]"]
  node_mysql[("MySQL database")]
  node_not_found["Not found error"]
  node_duplicate_alias["Duplicate alias error"]
  node_expired_link["Expired link error"]
end

node_client(("HTTP client"))

node_client -->|"submits URLs"| node_url_controller
node_client -->|"visits short link"| node_redirect_controller
node_client -->|"checks health"| node_health_controller
node_url_controller -->|"calls"| node_url_service
node_url_controller -->|"accepts"| node_create_request
node_url_controller -->|"returns"| node_short_response
node_url_controller -->|"returns"| node_analytics_response
node_redirect_controller -->|"calls"| node_url_service
node_url_service -->|"queries and saves"| node_url_repository
node_url_service -->|"builds and updates"| node_url_mapping
node_url_service -->|"generates codes"| node_code_generator
node_url_service -->|"checks aliases"| node_reserved_aliases
node_url_repository -.->|"persists mappings"| node_mysql
node_url_repository -->|"stores entity"| node_url_mapping
node_url_service -->|"throws"| node_not_found
node_url_service -->|"throws"| node_duplicate_alias
node_url_service -->|"throws"| node_expired_link
node_error_handler -->|"builds"| node_error_response
node_error_handler -->|"handles"| node_not_found
node_error_handler -->|"handles"| node_duplicate_alias
node_error_handler -->|"handles"| node_expired_link

click node_url_controller "https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/controller/UrlController.java"
click node_redirect_controller "https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/controller/RedirectController.java"
click node_health_controller "https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/controller/HealthController.java"
click node_error_handler "https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/exception/GlobalExceptionHandler.java"
click node_create_request "https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/dto/CreateShortUrlRequest.java"
click node_short_response "https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/dto/ShortUrlResponse.java"
click node_analytics_response "https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/dto/UrlAnalyticsResponse.java"
click node_error_response "https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/dto/ApiErrorResponse.java"
click node_url_service "https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/service/impl/UrlServiceImpl.java"
click node_code_generator "https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/util/ShortCodeGenerator.java"
click node_reserved_aliases "https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/util/ReservedAliases.java"
click node_url_mapping "https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/entity/UrlMapping.java"
click node_url_repository "https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/repository/UrlRepository.java"
click node_not_found "https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/exception/ShortUrlNotFoundException.java"
click node_duplicate_alias "https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/exception/DuplicateAliasException.java"
click node_expired_link "https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/exception/ExpiredLinkException.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_controller,node_redirect_controller,node_health_controller,node_error_handler,node_create_request,node_short_response,node_analytics_response,node_error_response,node_client toneBlue
class node_url_service,node_code_generator,node_reserved_aliases toneAmber
class node_url_mapping,node_url_repository,node_mysql,node_not_found,node_duplicate_alias,node_expired_link toneMint
```

## Components

### HTTP API

- [URL endpoints](https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/controller/UrlController.java): `src/main/java/com/urlshortener/controller/UrlController.java`
- [Redirect endpoint](https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/controller/RedirectController.java): `src/main/java/com/urlshortener/controller/RedirectController.java`
- [Health check](https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/controller/HealthController.java): `src/main/java/com/urlshortener/controller/HealthController.java`
- [Error mapping](https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/exception/GlobalExceptionHandler.java): `src/main/java/com/urlshortener/exception/GlobalExceptionHandler.java`
- [Create request](https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/dto/CreateShortUrlRequest.java): `src/main/java/com/urlshortener/dto/CreateShortUrlRequest.java`
- [Short URL response](https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/dto/ShortUrlResponse.java): `src/main/java/com/urlshortener/dto/ShortUrlResponse.java`
- [Analytics response](https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/dto/UrlAnalyticsResponse.java): `src/main/java/com/urlshortener/dto/UrlAnalyticsResponse.java`
- [Error response](https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/dto/ApiErrorResponse.java): `src/main/java/com/urlshortener/dto/ApiErrorResponse.java`

### URL workflows

- [URL service](https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/service/impl/UrlServiceImpl.java): `src/main/java/com/urlshortener/service/impl/UrlServiceImpl.java`
- [Code generation](https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/util/ShortCodeGenerator.java): `src/main/java/com/urlshortener/util/ShortCodeGenerator.java`
- [Reserved aliases](https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/util/ReservedAliases.java): `src/main/java/com/urlshortener/util/ReservedAliases.java`

### Persistence and errors

- [URL mapping](https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/entity/UrlMapping.java): `src/main/java/com/urlshortener/entity/UrlMapping.java`
- [URL repository](https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/repository/UrlRepository.java): `src/main/java/com/urlshortener/repository/UrlRepository.java`
- **MySQL database**
- [Not found error](https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/exception/ShortUrlNotFoundException.java): `src/main/java/com/urlshortener/exception/ShortUrlNotFoundException.java`
- [Duplicate alias error](https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/exception/DuplicateAliasException.java): `src/main/java/com/urlshortener/exception/DuplicateAliasException.java`
- [Expired link error](https://github.com/shravya33/url-shortener-service/blob/main/src/main/java/com/urlshortener/exception/ExpiredLinkException.java): `src/main/java/com/urlshortener/exception/ExpiredLinkException.java`

### Other components

- **HTTP client**

## Connections

- HTTP client → URL endpoints: submits URLs (evidence: `README.md`)
- HTTP client → Redirect endpoint: visits short link (evidence: `README.md`)
- HTTP client → Health check: checks health (evidence: `README.md`)
- URL endpoints → URL service: calls (evidence: `src/main/java/com/urlshortener/controller/UrlController.java`)
- URL endpoints → Create request: accepts (evidence: `src/main/java/com/urlshortener/controller/UrlController.java`)
- URL endpoints → Short URL response: returns (evidence: `src/main/java/com/urlshortener/controller/UrlController.java`)
- URL endpoints → Analytics response: returns (evidence: `src/main/java/com/urlshortener/controller/UrlController.java`)
- Redirect endpoint → URL service: calls (evidence: `src/main/java/com/urlshortener/controller/RedirectController.java`)
- URL service → URL repository: queries and saves (evidence: `src/main/java/com/urlshortener/service/impl/UrlServiceImpl.java`)
- URL service → URL mapping: builds and updates (evidence: `src/main/java/com/urlshortener/service/impl/UrlServiceImpl.java`)
- URL service → Code generation: generates codes (evidence: `src/main/java/com/urlshortener/service/impl/UrlServiceImpl.java`)
- URL service → Reserved aliases: checks aliases (evidence: `src/main/java/com/urlshortener/service/impl/UrlServiceImpl.java`)
- URL repository → MySQL database: persists mappings
- URL repository → URL mapping: stores entity (evidence: `src/main/java/com/urlshortener/repository/UrlRepository.java`)
- URL service → Not found error: throws (evidence: `src/main/java/com/urlshortener/service/impl/UrlServiceImpl.java`)
- URL service → Duplicate alias error: throws (evidence: `src/main/java/com/urlshortener/service/impl/UrlServiceImpl.java`)
- URL service → Expired link error: throws (evidence: `src/main/java/com/urlshortener/service/impl/UrlServiceImpl.java`)
- Error mapping → Error response: builds (evidence: `src/main/java/com/urlshortener/exception/GlobalExceptionHandler.java`)
- Error mapping → Not found error: handles (evidence: `src/main/java/com/urlshortener/exception/GlobalExceptionHandler.java`)
- Error mapping → Duplicate alias error: handles (evidence: `src/main/java/com/urlshortener/exception/GlobalExceptionHandler.java`)
- Error mapping → Expired link error: handles (evidence: `src/main/java/com/urlshortener/exception/GlobalExceptionHandler.java`)
