# basavaraj8143/url-shortener architecture

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

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

## Overview

This full-stack URL shortener turns authenticated users’ long URLs into short links, then redirects visitors while tracking clicks and expiry. The main workflow spans React URL creation and management, Spring controllers and services, persistent MySQL mappings, and a Redis-compatible redirect cache. Separate branches cover registration/login with JWT-protected requests, plus dashboard and analytics capabilities documented by the README. Frontend page wiring, most controllers, security configuration, and repositories were not excerpted, so uncertain internal calls are omitted; README-backed system links are documented edges.

Main entry points: [`src/main/java/com/buss/url_shortener/service/UrlService.java`](https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/service/UrlService.java) (URL service), [`frontend/src/pages`](https://github.com/basavaraj8143/url-shortener/tree/main/frontend/src/pages) (Pages and navigation), [`frontend/src/api/client.js`](https://github.com/basavaraj8143/url-shortener/blob/main/frontend/src/api/client.js) (HTTP client), [`src/main/java/com/buss/url_shortener/repository/UrlRepository.java`](https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/repository/UrlRepository.java) (URL repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React application"]
  node_webpages["Pages and navigation"]
  node_authcontext["Auth state<br/>[AuthContext.jsx]"]
  node_apiclient["HTTP client<br/>[client.js]"]
end

subgraph group_api["Spring API"]
  node_authcontroller["Auth endpoints"]
  node_urlcontroller["URL endpoints<br/>[UrlController.java]"]
  node_redirectcontroller["Redirect endpoint"]
  node_errors["Validation and API errors"]
end

subgraph group_identity["Identity and security"]
  node_authservice["Auth service<br/>[AuthService.java]"]
  node_jwtservice["JWT service<br/>[JwtService.java]"]
  node_security["JWT security filter"]
  node_userdetails["User details"]
end

subgraph group_url["URL lifecycle"]
  node_urlservice["URL service<br/>[UrlService.java]"]
  node_shortening["Shortening and aliases<br/>[UrlService.java]"]
  node_redirectlookup["Redirect lookup and clicks<br/>[UrlService.java]"]
  node_management["URL management and stats<br/>[UrlService.java]"]
end

subgraph group_data["Persistence and cache"]
  node_urlrepo["URL repository<br/>[UrlRepository.java]"]
  node_userrepo["User repository"]
  node_urlentity["URL records<br/>[Url.java]"]
  node_userentity["User records<br/>[AppUser.java]"]
  node_mysql[("MySQL")]
  node_valkey[("Valkey cache")]
end

node_visitor(("User / browser"))

node_visitor -->|"uses"| node_webpages
node_webpages -->|"requests"| node_apiclient
node_apiclient -.->|"REST requests"| node_urlcontroller
node_apiclient -.->|"REST requests"| node_authcontroller
node_webpages -->|"reads auth"| node_authcontext
node_authcontext -.->|"stores token"| node_apiclient
node_authcontroller -.->|"delegates"| node_authservice
node_authservice -->|"reads and saves"| node_userrepo
node_authservice -->|"issues token"| node_jwtservice
node_userdetails -->|"loads user"| node_userrepo
node_security -.->|"loads identity"| node_userdetails
node_webpages -->|"creates links"| node_urlcontroller
node_urlcontroller -.->|"delegates"| node_urlservice
node_urlservice -->|"processes request"| node_shortening
node_urlservice -->|"lists and measures"| node_management
node_urlservice -->|"resolves code"| node_redirectlookup
node_redirectcontroller -->|"gets destination"| node_urlservice
node_shortening -->|"checks and saves"| node_urlrepo
node_management -->|"reads and deletes"| node_urlrepo
node_redirectlookup -->|"reads and updates"| node_urlrepo
node_shortening -->|"finds owner"| node_userrepo
node_urlrepo -.->|"persists mappings"| node_mysql
node_userrepo -.->|"persists users"| node_mysql
node_redirectlookup -->|"checks and caches"| node_valkey
node_errors -.->|"returns API errors"| node_visitor

click node_webpages "https://github.com/basavaraj8143/url-shortener/tree/main/frontend/src/pages"
click node_authcontext "https://github.com/basavaraj8143/url-shortener/blob/main/frontend/src/context/AuthContext.jsx"
click node_apiclient "https://github.com/basavaraj8143/url-shortener/blob/main/frontend/src/api/client.js"
click node_authcontroller "https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/controller/AuthController.java"
click node_urlcontroller "https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/controller/UrlController.java"
click node_redirectcontroller "https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/controller/RedirectController.java"
click node_authservice "https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/service/AuthService.java"
click node_jwtservice "https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/service/JwtService.java"
click node_security "https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/config/JwtAuthenticationFilter.java"
click node_userdetails "https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/service/CustomUserDetailsService.java"
click node_urlservice "https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/service/UrlService.java"
click node_shortening "https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/service/UrlService.java"
click node_redirectlookup "https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/service/UrlService.java"
click node_management "https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/service/UrlService.java"
click node_errors "https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/exception/GlobalExceptionHandler.java"
click node_urlrepo "https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/repository/UrlRepository.java"
click node_userrepo "https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/repository/UserRepository.java"
click node_urlentity "https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/entity/Url.java"
click node_userentity "https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/entity/AppUser.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_webpages,node_authcontext,node_apiclient,node_visitor toneBlue
class node_authcontroller,node_urlcontroller,node_redirectcontroller,node_errors toneAmber
class node_authservice,node_jwtservice,node_security,node_userdetails toneMint
class node_urlservice,node_shortening,node_redirectlookup,node_management toneRose
class node_urlrepo,node_userrepo,node_urlentity,node_userentity,node_mysql,node_valkey toneIndigo
```

## Components

### React application

- [Pages and navigation](https://github.com/basavaraj8143/url-shortener/tree/main/frontend/src/pages): `frontend/src/pages`
- [Auth state](https://github.com/basavaraj8143/url-shortener/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [HTTP client](https://github.com/basavaraj8143/url-shortener/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`

### Spring API

- [Auth endpoints](https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/controller/AuthController.java): `src/main/java/com/buss/url_shortener/controller/AuthController.java`
- [URL endpoints](https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/controller/UrlController.java): `src/main/java/com/buss/url_shortener/controller/UrlController.java`
- [Redirect endpoint](https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/controller/RedirectController.java): `src/main/java/com/buss/url_shortener/controller/RedirectController.java`
- [Validation and API errors](https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/exception/GlobalExceptionHandler.java): `src/main/java/com/buss/url_shortener/exception/GlobalExceptionHandler.java`

### Identity and security

- [Auth service](https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/service/AuthService.java): `src/main/java/com/buss/url_shortener/service/AuthService.java`
- [JWT service](https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/service/JwtService.java): `src/main/java/com/buss/url_shortener/service/JwtService.java`
- [JWT security filter](https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/config/JwtAuthenticationFilter.java): `src/main/java/com/buss/url_shortener/config/JwtAuthenticationFilter.java`
- [User details](https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/service/CustomUserDetailsService.java): `src/main/java/com/buss/url_shortener/service/CustomUserDetailsService.java`

### URL lifecycle

- [URL service](https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/service/UrlService.java): `src/main/java/com/buss/url_shortener/service/UrlService.java`
- [Shortening and aliases](https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/service/UrlService.java): `src/main/java/com/buss/url_shortener/service/UrlService.java`
- [Redirect lookup and clicks](https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/service/UrlService.java): `src/main/java/com/buss/url_shortener/service/UrlService.java`
- [URL management and stats](https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/service/UrlService.java): `src/main/java/com/buss/url_shortener/service/UrlService.java`

### Persistence and cache

- [URL repository](https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/repository/UrlRepository.java): `src/main/java/com/buss/url_shortener/repository/UrlRepository.java`
- [User repository](https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/repository/UserRepository.java): `src/main/java/com/buss/url_shortener/repository/UserRepository.java`
- [URL records](https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/entity/Url.java): `src/main/java/com/buss/url_shortener/entity/Url.java`
- [User records](https://github.com/basavaraj8143/url-shortener/blob/main/src/main/java/com/buss/url_shortener/entity/AppUser.java): `src/main/java/com/buss/url_shortener/entity/AppUser.java`
- **MySQL**
- **Valkey cache**

### Other components

- **User / browser**

## Connections

- User / browser → Pages and navigation: uses
- Pages and navigation → HTTP client: requests (evidence: `frontend/src/pages/Landing.jsx`)
- HTTP client → URL endpoints: REST requests
- HTTP client → Auth endpoints: REST requests
- Pages and navigation → Auth state: reads auth (evidence: `frontend/src/pages/Landing.jsx`)
- Auth state → HTTP client: stores token
- Auth endpoints → Auth service: delegates
- Auth service → User repository: reads and saves (evidence: `src/main/java/com/buss/url_shortener/service/AuthService.java`)
- Auth service → JWT service: issues token (evidence: `src/main/java/com/buss/url_shortener/service/AuthService.java`)
- User details → User repository: loads user (evidence: `src/main/java/com/buss/url_shortener/service/CustomUserDetailsService.java`)
- JWT security filter → User details: loads identity
- Pages and navigation → URL endpoints: creates links (evidence: `frontend/src/pages/Landing.jsx`)
- URL endpoints → URL service: delegates
- URL service → Shortening and aliases: processes request (evidence: `src/main/java/com/buss/url_shortener/service/UrlService.java`)
- URL service → URL management and stats: lists and measures (evidence: `src/main/java/com/buss/url_shortener/service/UrlService.java`)
- URL service → Redirect lookup and clicks: resolves code (evidence: `src/main/java/com/buss/url_shortener/service/UrlService.java`)
- Redirect endpoint → URL service: gets destination (evidence: `src/main/java/com/buss/url_shortener/controller/RedirectController.java`)
- Shortening and aliases → URL repository: checks and saves (evidence: `src/main/java/com/buss/url_shortener/service/UrlService.java`)
- URL management and stats → URL repository: reads and deletes (evidence: `src/main/java/com/buss/url_shortener/service/UrlService.java`)
- Redirect lookup and clicks → URL repository: reads and updates (evidence: `src/main/java/com/buss/url_shortener/service/UrlService.java`)
- Shortening and aliases → User repository: finds owner (evidence: `src/main/java/com/buss/url_shortener/service/UrlService.java`)
- URL repository → MySQL: persists mappings
- User repository → MySQL: persists users
- Redirect lookup and clicks → Valkey cache: checks and caches (evidence: `src/main/java/com/buss/url_shortener/service/UrlService.java`)
- Validation and API errors → User / browser: returns API errors