# suryavamsi-kothapalli/url-shortener architecture

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

- Interactive diagram: https://gitdiagram.com/suryavamsi-kothapalli/url-shortener
- Repository: https://github.com/suryavamsi-kothapalli/url-shortener

## Overview

This is a Spring Boot URL-shortening web application: users submit long URLs to receive Base62 short links, then visit those links to be redirected to the saved destinations. The graph follows both documented request flows and includes validation, persistence, API payloads, and error handling. The service implementation and controllers were excerpted; frontend and database links are based on the README, so unsampled implementation details are not inferred.

Main entry points: [`src/main/java/com/urlshortener/service/UrlShortenerServiceImpl.java`](https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/service/UrlShortenerServiceImpl.java) (Shortening service), [`src/main/java/com/urlshortener/repository/UrlRepository.java`](https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/repository/UrlRepository.java) (URL repository), [`src/main/java/com/urlshortener/controller/UrlRestController.java`](https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/controller/UrlRestController.java) (Create URL API), [`src/main/java/com/urlshortener/exception/GlobalExceptionHandler.java`](https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/exception/GlobalExceptionHandler.java) (API error handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_frontend["Short-link UI<br/>[app.js]"]
end

subgraph group_api["HTTP endpoints"]
  node_rest["Create URL API"]
  node_redirect["Redirect endpoint"]
  node_request["Shorten request"]
  node_response["Shorten response"]
  node_errorhandler["API error handler"]
  node_errorresponse["Error payload<br/>[ErrorResponse.java]"]
end

subgraph group_domain["Shortening domain"]
  node_invalid["Invalid URL error"]
  node_notfound["URL not found error"]
  node_service["Shortening service"]
  node_validator["URL validation<br/>[UrlValidator.java]"]
  node_base62["Base62 codec<br/>[Base62.java]"]
end

subgraph group_storage["Persistence"]
  node_repository["URL repository<br/>[UrlRepository.java]"]
  node_entity["URL record<br/>[UrlEntity.java]"]
  node_mysql[("MySQL database")]
end

node_user(("User / browser"))
node_target(("Destination website"))

node_user -->|"enters URL"| node_frontend
node_frontend -->|"submits URL"| node_rest
node_rest -->|"accepts payload"| node_request
node_rest -->|"requests shortening"| node_service
node_service -->|"validates URL"| node_validator
node_service -->|"throws on invalid"| node_invalid
node_service -->|"saves record"| node_repository
node_repository -->|"persists record"| node_mysql
node_repository -->|"stores entity"| node_entity
node_service -->|"encodes ID"| node_base62
node_service -->|"returns short URL"| node_response
node_rest -->|"builds payload"| node_response
node_user -->|"visits short link"| node_redirect
node_redirect -->|"resolves code"| node_service
node_service -->|"decodes code"| node_base62
node_service -->|"looks up ID"| node_repository
node_repository -->|"reads record"| node_mysql
node_redirect -->|"redirects browser"| node_target
node_errorhandler -->|"builds error payload"| node_errorresponse
node_errorhandler -->|"handles validation error"| node_invalid
node_errorhandler -->|"handles missing URL"| node_notfound
node_service -->|"throws when absent"| node_notfound

click node_frontend "https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/resources/static/js/app.js"
click node_rest "https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/controller/UrlRestController.java"
click node_redirect "https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/controller/UrlRedirectController.java"
click node_request "https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/dto/ShortenRequest.java"
click node_response "https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/dto/ShortenResponse.java"
click node_errorhandler "https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/exception/GlobalExceptionHandler.java"
click node_errorresponse "https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/dto/ErrorResponse.java"
click node_invalid "https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/exception/InvalidUrlException.java"
click node_notfound "https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/exception/UrlNotFoundException.java"
click node_service "https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/service/UrlShortenerServiceImpl.java"
click node_validator "https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/util/UrlValidator.java"
click node_base62 "https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/util/Base62.java"
click node_repository "https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/repository/UrlRepository.java"
click node_entity "https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/entity/UrlEntity.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_frontend,node_user toneBlue
class node_rest,node_redirect,node_request,node_response,node_errorhandler,node_errorresponse toneAmber
class node_invalid,node_notfound,node_service,node_validator,node_base62 toneMint
class node_repository,node_entity,node_mysql toneRose
class node_target toneIndigo
```

## Components

### Web client

- [Short-link UI](https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/resources/static/js/app.js): `src/main/resources/static/js/app.js`

### HTTP endpoints

- [Create URL API](https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/controller/UrlRestController.java): `src/main/java/com/urlshortener/controller/UrlRestController.java`
- [Redirect endpoint](https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/controller/UrlRedirectController.java): `src/main/java/com/urlshortener/controller/UrlRedirectController.java`
- [Shorten request](https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/dto/ShortenRequest.java): `src/main/java/com/urlshortener/dto/ShortenRequest.java`
- [Shorten response](https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/dto/ShortenResponse.java): `src/main/java/com/urlshortener/dto/ShortenResponse.java`
- [API error handler](https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/exception/GlobalExceptionHandler.java): `src/main/java/com/urlshortener/exception/GlobalExceptionHandler.java`
- [Error payload](https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/dto/ErrorResponse.java): `src/main/java/com/urlshortener/dto/ErrorResponse.java`

### Shortening domain

- [Invalid URL error](https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/exception/InvalidUrlException.java): `src/main/java/com/urlshortener/exception/InvalidUrlException.java`
- [URL not found error](https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/exception/UrlNotFoundException.java): `src/main/java/com/urlshortener/exception/UrlNotFoundException.java`
- [Shortening service](https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/service/UrlShortenerServiceImpl.java): `src/main/java/com/urlshortener/service/UrlShortenerServiceImpl.java`
- [URL validation](https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/util/UrlValidator.java): `src/main/java/com/urlshortener/util/UrlValidator.java`
- [Base62 codec](https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/util/Base62.java): `src/main/java/com/urlshortener/util/Base62.java`

### Persistence

- [URL repository](https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/repository/UrlRepository.java): `src/main/java/com/urlshortener/repository/UrlRepository.java`
- [URL record](https://github.com/suryavamsi-kothapalli/url-shortener/blob/main/src/main/java/com/urlshortener/entity/UrlEntity.java): `src/main/java/com/urlshortener/entity/UrlEntity.java`
- **MySQL database**

### Other components

- **User / browser**
- **Destination website**

## Connections

- User / browser → Short-link UI: enters URL (evidence: `README.md`)
- Short-link UI → Create URL API: submits URL (evidence: `README.md`)
- Create URL API → Shorten request: accepts payload (evidence: `src/main/java/com/urlshortener/controller/UrlRestController.java`)
- Create URL API → Shortening service: requests shortening (evidence: `src/main/java/com/urlshortener/controller/UrlRestController.java`)
- Shortening service → URL validation: validates URL (evidence: `src/main/java/com/urlshortener/service/UrlShortenerServiceImpl.java`)
- Shortening service → Invalid URL error: throws on invalid (evidence: `src/main/java/com/urlshortener/service/UrlShortenerServiceImpl.java`)
- Shortening service → URL repository: saves record (evidence: `src/main/java/com/urlshortener/service/UrlShortenerServiceImpl.java`)
- URL repository → MySQL database: persists record (evidence: `README.md`)
- URL repository → URL record: stores entity (evidence: `src/main/java/com/urlshortener/repository/UrlRepository.java`)
- Shortening service → Base62 codec: encodes ID (evidence: `src/main/java/com/urlshortener/service/UrlShortenerServiceImpl.java`)
- Shortening service → Shorten response: returns short URL (evidence: `README.md`)
- Create URL API → Shorten response: builds payload (evidence: `src/main/java/com/urlshortener/controller/UrlRestController.java`)
- User / browser → Redirect endpoint: visits short link (evidence: `README.md`)
- Redirect endpoint → Shortening service: resolves code (evidence: `src/main/java/com/urlshortener/controller/UrlRedirectController.java`)
- Shortening service → Base62 codec: decodes code (evidence: `src/main/java/com/urlshortener/service/UrlShortenerServiceImpl.java`)
- Shortening service → URL repository: looks up ID (evidence: `src/main/java/com/urlshortener/service/UrlShortenerServiceImpl.java`)
- URL repository → MySQL database: reads record (evidence: `README.md`)
- Redirect endpoint → Destination website: redirects browser (evidence: `README.md`)
- API error handler → Error payload: builds error payload (evidence: `src/main/java/com/urlshortener/exception/GlobalExceptionHandler.java`)
- API error handler → Invalid URL error: handles validation error (evidence: `src/main/java/com/urlshortener/exception/GlobalExceptionHandler.java`)
- API error handler → URL not found error: handles missing URL (evidence: `src/main/java/com/urlshortener/exception/GlobalExceptionHandler.java`)
- Shortening service → URL not found error: throws when absent (evidence: `src/main/java/com/urlshortener/service/UrlShortenerServiceImpl.java`)
