# kushelwho/url-shortener architecture

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

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

## Overview

This is a full-stack URL shortener: React provides registration/login, a protected dashboard, link creation and click charts; Spring Boot exposes authentication, shortening, redirect and analytics APIs backed by persistent user, mapping and click-event data. The principal flow is authenticated URL creation, followed by public short-link resolution and click recording. Edges reflect shown calls and README-documented interactions; some frontend API wiring and security configuration were not sampled, so those links are omitted or marked as documented.

Main entry points: [`url-shortener-react/src/AppRouter.jsx`](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-react/src/AppRouter.jsx) (Page routing), [`url-shortener-sb/src/main/java/com/url/shortener/service/UserService.java`](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/service/UserService.java) (User service), [`url-shortener-sb/src/main/java/com/url/shortener/controller/UrlMappingController.java`](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/controller/UrlMappingController.java) (URL management API), [`url-shortener-sb/src/main/java/com/url/shortener/service/UrlMappingService.java`](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/service/UrlMappingService.java) (URL and analytics service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["React interface"]
  node_app["React app<br/>[App.jsx]"]
  node_routes["Page routing<br/>[AppRouter.jsx]"]
  node_context["Token context<br/>[ContextApi.jsx]"]
  node_authpages["Login and register<br/>[RegisterPage.jsx]"]
  node_dashboard["Dashboard"]
  node_linkitem["Link actions<br/>[ShortenItem.jsx]"]
  node_charts["Click charts<br/>[Graph.jsx]"]
  node_queries["Dashboard queries<br/>[useQuery.js]"]
  node_http["HTTP client<br/>[api.js]"]
end

subgraph group_auth["Authentication"]
  node_authapi["Authentication API"]
  node_userservice["User service<br/>[UserService.java]"]
  node_jwt["JWT utilities<br/>[JwtUtils.java]"]
  node_jwtfilter["JWT filter"]
end

subgraph group_links["Shortening and analytics"]
  node_urlapi["URL management API"]
  node_urlservice["URL and analytics service"]
  node_redirect["Short-link redirect"]
end

subgraph group_data["Persistent data"]
  node_userrepo["User repository"]
  node_urlrepo["URL repository"]
  node_clickrepo["Click repository"]
  node_user[("User records<br/>[User.java]")]
  node_mapping[("URL mappings<br/>[UrlMapping.java]")]
  node_click[("Click events<br/>[ClickEvent.java]")]
end

node_visitor(("Visitor"))
node_destination(("Original destination"))

node_visitor -->|"opens pages"| node_routes
node_app -.->|"selects app"| node_routes
node_routes -->|"routes to"| node_authpages
node_routes -->|"routes to"| node_dashboard
node_routes -.->|"serves redirect page"| node_visitor
node_dashboard -->|"fetches data"| node_queries
node_dashboard -->|"renders chart"| node_charts
node_linkitem -->|"sends requests"| node_http
node_queries -->|"requests data"| node_http
node_context -.->|"shares token"| node_authpages
node_visitor -->|"registers or logs in"| node_authapi
node_authapi -->|"delegates"| node_userservice
node_userservice -->|"reads and saves"| node_userrepo
node_userservice -->|"creates token"| node_jwt
node_jwtfilter -->|"validates token"| node_jwt
node_http -.->|"calls endpoints"| node_urlapi
node_visitor -->|"requests shortening"| node_urlapi
node_urlapi -->|"resolves user"| node_userservice
node_urlapi -->|"delegates"| node_urlservice
node_urlservice -->|"reads and saves"| node_urlrepo
node_urlservice -->|"records and queries"| node_clickrepo
node_redirect -->|"resolves short code"| node_urlservice
node_visitor -->|"opens short link"| node_redirect
node_redirect -->|"redirects to"| node_destination
node_userrepo -.->|"persists"| node_user
node_urlrepo -.->|"persists"| node_mapping
node_clickrepo -.->|"persists"| node_click

click node_app "https://github.com/kushelwho/url-shortener/blob/main/url-shortener-react/src/App.jsx"
click node_routes "https://github.com/kushelwho/url-shortener/blob/main/url-shortener-react/src/AppRouter.jsx"
click node_context "https://github.com/kushelwho/url-shortener/blob/main/url-shortener-react/src/contextApi/ContextApi.jsx"
click node_authpages "https://github.com/kushelwho/url-shortener/blob/main/url-shortener-react/src/components/RegisterPage.jsx"
click node_dashboard "https://github.com/kushelwho/url-shortener/blob/main/url-shortener-react/src/components/Dashboard/DashboardLayout.jsx"
click node_linkitem "https://github.com/kushelwho/url-shortener/blob/main/url-shortener-react/src/components/Dashboard/ShortenItem.jsx"
click node_charts "https://github.com/kushelwho/url-shortener/blob/main/url-shortener-react/src/components/Dashboard/Graph.jsx"
click node_queries "https://github.com/kushelwho/url-shortener/blob/main/url-shortener-react/src/hooks/useQuery.js"
click node_http "https://github.com/kushelwho/url-shortener/blob/main/url-shortener-react/src/api/api.js"
click node_authapi "https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/controller/AuthController.java"
click node_userservice "https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/service/UserService.java"
click node_jwt "https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/security/jwt/JwtUtils.java"
click node_jwtfilter "https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/security/jwt/JwtAuthenticationFilter.java"
click node_urlapi "https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/controller/UrlMappingController.java"
click node_urlservice "https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/service/UrlMappingService.java"
click node_redirect "https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/controller/RedirectController.java"
click node_userrepo "https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/repository/UserRepository.java"
click node_urlrepo "https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/repository/UrlMappingRepository.java"
click node_clickrepo "https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/repository/ClickEventRepository.java"
click node_user "https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/models/User.java"
click node_mapping "https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/models/UrlMapping.java"
click node_click "https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/models/ClickEvent.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_app,node_routes,node_context,node_authpages,node_dashboard,node_linkitem,node_charts,node_queries,node_http toneBlue
class node_authapi,node_userservice,node_jwt,node_jwtfilter toneAmber
class node_urlapi,node_urlservice,node_redirect toneMint
class node_userrepo,node_urlrepo,node_clickrepo,node_user,node_mapping,node_click toneRose
class node_visitor,node_destination toneIndigo
```

## Components

### React interface

- [React app](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-react/src/App.jsx): `url-shortener-react/src/App.jsx`
- [Page routing](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-react/src/AppRouter.jsx): `url-shortener-react/src/AppRouter.jsx`
- [Token context](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-react/src/contextApi/ContextApi.jsx): `url-shortener-react/src/contextApi/ContextApi.jsx`
- [Login and register](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-react/src/components/RegisterPage.jsx): `url-shortener-react/src/components/RegisterPage.jsx`
- [Dashboard](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-react/src/components/Dashboard/DashboardLayout.jsx): `url-shortener-react/src/components/Dashboard/DashboardLayout.jsx`
- [Link actions](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-react/src/components/Dashboard/ShortenItem.jsx): `url-shortener-react/src/components/Dashboard/ShortenItem.jsx`
- [Click charts](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-react/src/components/Dashboard/Graph.jsx): `url-shortener-react/src/components/Dashboard/Graph.jsx`
- [Dashboard queries](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-react/src/hooks/useQuery.js): `url-shortener-react/src/hooks/useQuery.js`
- [HTTP client](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-react/src/api/api.js): `url-shortener-react/src/api/api.js`

### Authentication

- [Authentication API](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/controller/AuthController.java): `url-shortener-sb/src/main/java/com/url/shortener/controller/AuthController.java`
- [User service](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/service/UserService.java): `url-shortener-sb/src/main/java/com/url/shortener/service/UserService.java`
- [JWT utilities](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/security/jwt/JwtUtils.java): `url-shortener-sb/src/main/java/com/url/shortener/security/jwt/JwtUtils.java`
- [JWT filter](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/security/jwt/JwtAuthenticationFilter.java): `url-shortener-sb/src/main/java/com/url/shortener/security/jwt/JwtAuthenticationFilter.java`

### Shortening and analytics

- [URL management API](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/controller/UrlMappingController.java): `url-shortener-sb/src/main/java/com/url/shortener/controller/UrlMappingController.java`
- [URL and analytics service](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/service/UrlMappingService.java): `url-shortener-sb/src/main/java/com/url/shortener/service/UrlMappingService.java`
- [Short-link redirect](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/controller/RedirectController.java): `url-shortener-sb/src/main/java/com/url/shortener/controller/RedirectController.java`

### Persistent data

- [User repository](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/repository/UserRepository.java): `url-shortener-sb/src/main/java/com/url/shortener/repository/UserRepository.java`
- [URL repository](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/repository/UrlMappingRepository.java): `url-shortener-sb/src/main/java/com/url/shortener/repository/UrlMappingRepository.java`
- [Click repository](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/repository/ClickEventRepository.java): `url-shortener-sb/src/main/java/com/url/shortener/repository/ClickEventRepository.java`
- [User records](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/models/User.java): `url-shortener-sb/src/main/java/com/url/shortener/models/User.java`
- [URL mappings](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/models/UrlMapping.java): `url-shortener-sb/src/main/java/com/url/shortener/models/UrlMapping.java`
- [Click events](https://github.com/kushelwho/url-shortener/blob/main/url-shortener-sb/src/main/java/com/url/shortener/models/ClickEvent.java): `url-shortener-sb/src/main/java/com/url/shortener/models/ClickEvent.java`

### Other components

- **Visitor**
- **Original destination**

## Connections

- Visitor → Page routing: opens pages (evidence: `url-shortener-react/src/AppRouter.jsx`)
- React app → Page routing: selects app
- Page routing → Login and register: routes to (evidence: `url-shortener-react/src/AppRouter.jsx`)
- Page routing → Dashboard: routes to (evidence: `url-shortener-react/src/AppRouter.jsx`)
- Page routing → Visitor: serves redirect page
- Dashboard → Dashboard queries: fetches data (evidence: `url-shortener-react/src/components/Dashboard/DashboardLayout.jsx`)
- Dashboard → Click charts: renders chart (evidence: `url-shortener-react/src/components/Dashboard/DashboardLayout.jsx`)
- Link actions → HTTP client: sends requests (evidence: `url-shortener-react/src/components/Dashboard/ShortenItem.jsx`)
- Dashboard queries → HTTP client: requests data (evidence: `url-shortener-react/src/hooks/useQuery.js`)
- Token context → Login and register: shares token
- Visitor → Authentication API: registers or logs in (evidence: `README.md`)
- Authentication API → User service: delegates (evidence: `url-shortener-sb/src/main/java/com/url/shortener/controller/AuthController.java`)
- User service → User repository: reads and saves (evidence: `url-shortener-sb/src/main/java/com/url/shortener/service/UserService.java`)
- User service → JWT utilities: creates token (evidence: `url-shortener-sb/src/main/java/com/url/shortener/service/UserService.java`)
- JWT filter → JWT utilities: validates token (evidence: `url-shortener-sb/src/main/java/com/url/shortener/security/jwt/JwtAuthenticationFilter.java`)
- HTTP client → URL management API: calls endpoints (evidence: `README.md`)
- Visitor → URL management API: requests shortening (evidence: `README.md`)
- URL management API → User service: resolves user (evidence: `url-shortener-sb/src/main/java/com/url/shortener/controller/UrlMappingController.java`)
- URL management API → URL and analytics service: delegates (evidence: `url-shortener-sb/src/main/java/com/url/shortener/controller/UrlMappingController.java`)
- URL and analytics service → URL repository: reads and saves (evidence: `url-shortener-sb/src/main/java/com/url/shortener/service/UrlMappingService.java`)
- URL and analytics service → Click repository: records and queries (evidence: `url-shortener-sb/src/main/java/com/url/shortener/service/UrlMappingService.java`)
- Short-link redirect → URL and analytics service: resolves short code (evidence: `url-shortener-sb/src/main/java/com/url/shortener/controller/RedirectController.java`)
- Visitor → Short-link redirect: opens short link (evidence: `README.md`)
- Short-link redirect → Original destination: redirects to (evidence: `README.md`)
- User repository → User records: persists (evidence: `url-shortener-sb/src/main/java/com/url/shortener/repository/UserRepository.java`)
- URL repository → URL mappings: persists (evidence: `url-shortener-sb/src/main/java/com/url/shortener/repository/UrlMappingRepository.java`)
- Click repository → Click events: persists (evidence: `url-shortener-sb/src/main/java/com/url/shortener/repository/ClickEventRepository.java`)
