# davidandr1/url-shortener architecture

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

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

## Overview

SwiftURL is a full-stack short-link service. A user registers or logs in, submits a long URL, and receives a Base62 link; visitors follow that link to be redirected, while click data is queued for asynchronous persistence. Authenticated users can list their links. The graph includes the documented Redis cache, expiry behavior, and hashed-IP click tracking. Some subsystems are documented but their implementation was not sampled, so those relationships are shown only where the README or excerpts support them.

Main entry points: [`backend/src/main/java/com/davidandriychuk/url_shortener/controller/LinkController.java`](https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/controller/LinkController.java) (Link endpoints), [`frontend/src/App.jsx`](https://github.com/davidandr1/url-shortener/blob/main/frontend/src/App.jsx) (React app), [`backend/src/main/java/com/davidandriychuk/url_shortener/service/LinkService.java`](https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/service/LinkService.java) (Cached lookup and expiry), [`backend/src/main/java/com/davidandriychuk/url_shortener/repository/UserRepository.java`](https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/repository/UserRepository.java) (User repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["React app<br/>[App.jsx]"]
end

subgraph group_identity["Identity and access"]
  node_auth["Auth endpoints"]
  node_registration["User registration"]
  node_security["JWT security"]
  node_jwt["JWT issue and validation<br/>[JWTGenerator.java]"]
  node_jwtfilter["JWT request filter"]
  node_userdetails["User lookup"]
  node_users["User repository"]
end

subgraph group_links["Link lifecycle"]
  node_linkapi["Link endpoints"]
  node_linkservice["Cached lookup and expiry<br/>[LinkService.java]"]
  node_linkrepo["Link repository"]
  node_link["Link and Base62 code<br/>[Link.java]"]
  node_redis[("Redis cache")]
end

subgraph group_analytics["Click analytics"]
  node_rabbitconfig["RabbitMQ routing config<br/>[RabbitConfig.java]"]
  node_queue["RabbitMQ"]
  node_consumer["Click event consumer"]
  node_iphash["Visitor IP hashing<br/>[IpHasher.java]"]
  node_clickrepo["Click event repository"]
end

node_user(("User"))
node_postgres[("PostgreSQL")]

node_user -->|"uses"| node_app
node_app -->|"logs in"| node_auth
node_app -->|"registers"| node_registration
node_app -->|"creates and lists"| node_linkapi
node_auth -->|"issues token"| node_jwt
node_security -->|"registers filter"| node_jwtfilter
node_jwtfilter -->|"validates token"| node_jwt
node_jwtfilter -->|"loads identity"| node_userdetails
node_userdetails -->|"looks up user"| node_users
node_registration -->|"persists user"| node_users
node_linkapi -->|"resolves owner"| node_users
node_linkapi -->|"saves and lists"| node_linkrepo
node_linkapi -->|"encodes code"| node_link
node_linkapi -->|"resolves redirect"| node_linkservice
node_linkservice -->|"loads by id"| node_linkrepo
node_linkservice -->|"decodes and checks"| node_link
node_linkservice -->|"caches lookup"| node_redis
node_linkrepo -->|"persists links"| node_postgres
node_users -->|"persists users"| node_postgres
node_linkapi -->|"uses routing"| node_rabbitconfig
node_linkapi -->|"publishes click"| node_queue
node_rabbitconfig -.->|"configures route"| node_queue
node_queue -->|"delivers event"| node_consumer
node_consumer -->|"hashes visitor IP"| node_iphash
node_consumer -->|"saves click"| node_clickrepo
node_clickrepo -->|"persists events"| node_postgres

click node_app "https://github.com/davidandr1/url-shortener/blob/main/frontend/src/App.jsx"
click node_auth "https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/controller/AuthController.java"
click node_registration "https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/controller/UserController.java"
click node_security "https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/security/SecurityConfig.java"
click node_jwt "https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/security/JWTGenerator.java"
click node_jwtfilter "https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/security/JWTAuthenticationFilter.java"
click node_userdetails "https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/service/CustomUserDetailsService.java"
click node_users "https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/repository/UserRepository.java"
click node_linkapi "https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/controller/LinkController.java"
click node_linkservice "https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/service/LinkService.java"
click node_linkrepo "https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/repository/LinkRepository.java"
click node_link "https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/entity/Link.java"
click node_rabbitconfig "https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/config/RabbitConfig.java"
click node_consumer "https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/messaging/ClickEventConsumer.java"
click node_iphash "https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/util/IpHasher.java"
click node_clickrepo "https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/repository/ClickEventRepository.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_user toneBlue
class node_auth,node_registration,node_security,node_jwt,node_jwtfilter,node_userdetails,node_users,node_postgres toneAmber
class node_linkapi,node_linkservice,node_linkrepo,node_link,node_redis toneMint
class node_rabbitconfig,node_queue,node_consumer,node_iphash,node_clickrepo toneRose
```

## Components

### Web client

- [React app](https://github.com/davidandr1/url-shortener/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`

### Identity and access

- [Auth endpoints](https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/controller/AuthController.java): `backend/src/main/java/com/davidandriychuk/url_shortener/controller/AuthController.java`
- [User registration](https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/controller/UserController.java): `backend/src/main/java/com/davidandriychuk/url_shortener/controller/UserController.java`
- [JWT security](https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/security/SecurityConfig.java): `backend/src/main/java/com/davidandriychuk/url_shortener/security/SecurityConfig.java`
- [JWT issue and validation](https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/security/JWTGenerator.java): `backend/src/main/java/com/davidandriychuk/url_shortener/security/JWTGenerator.java`
- [JWT request filter](https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/security/JWTAuthenticationFilter.java): `backend/src/main/java/com/davidandriychuk/url_shortener/security/JWTAuthenticationFilter.java`
- [User lookup](https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/service/CustomUserDetailsService.java): `backend/src/main/java/com/davidandriychuk/url_shortener/service/CustomUserDetailsService.java`
- [User repository](https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/repository/UserRepository.java): `backend/src/main/java/com/davidandriychuk/url_shortener/repository/UserRepository.java`

### Link lifecycle

- [Link endpoints](https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/controller/LinkController.java): `backend/src/main/java/com/davidandriychuk/url_shortener/controller/LinkController.java`
- [Cached lookup and expiry](https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/service/LinkService.java): `backend/src/main/java/com/davidandriychuk/url_shortener/service/LinkService.java`
- [Link repository](https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/repository/LinkRepository.java): `backend/src/main/java/com/davidandriychuk/url_shortener/repository/LinkRepository.java`
- [Link and Base62 code](https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/entity/Link.java): `backend/src/main/java/com/davidandriychuk/url_shortener/entity/Link.java`
- **Redis cache**

### Click analytics

- [RabbitMQ routing config](https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/config/RabbitConfig.java): `backend/src/main/java/com/davidandriychuk/url_shortener/config/RabbitConfig.java`
- **RabbitMQ**
- [Click event consumer](https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/messaging/ClickEventConsumer.java): `backend/src/main/java/com/davidandriychuk/url_shortener/messaging/ClickEventConsumer.java`
- [Visitor IP hashing](https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/util/IpHasher.java): `backend/src/main/java/com/davidandriychuk/url_shortener/util/IpHasher.java`
- [Click event repository](https://github.com/davidandr1/url-shortener/blob/main/backend/src/main/java/com/davidandriychuk/url_shortener/repository/ClickEventRepository.java): `backend/src/main/java/com/davidandriychuk/url_shortener/repository/ClickEventRepository.java`

### Other components

- **User**
- **PostgreSQL**

## Connections

- User → React app: uses (evidence: `frontend/src/App.jsx`)
- React app → Auth endpoints: logs in (evidence: `frontend/src/App.jsx`)
- React app → User registration: registers (evidence: `README.md`)
- React app → Link endpoints: creates and lists (evidence: `frontend/src/App.jsx`)
- Auth endpoints → JWT issue and validation: issues token (evidence: `backend/src/main/java/com/davidandriychuk/url_shortener/controller/AuthController.java`)
- JWT security → JWT request filter: registers filter (evidence: `backend/src/main/java/com/davidandriychuk/url_shortener/security/SecurityConfig.java`)
- JWT request filter → JWT issue and validation: validates token (evidence: `backend/src/main/java/com/davidandriychuk/url_shortener/security/JWTAuthenticationFilter.java`)
- JWT request filter → User lookup: loads identity (evidence: `backend/src/main/java/com/davidandriychuk/url_shortener/security/JWTAuthenticationFilter.java`)
- User lookup → User repository: looks up user (evidence: `backend/src/main/java/com/davidandriychuk/url_shortener/service/CustomUserDetailsService.java`)
- User registration → User repository: persists user (evidence: `backend/src/main/java/com/davidandriychuk/url_shortener/controller/UserController.java`)
- Link endpoints → User repository: resolves owner (evidence: `backend/src/main/java/com/davidandriychuk/url_shortener/controller/LinkController.java`)
- Link endpoints → Link repository: saves and lists (evidence: `backend/src/main/java/com/davidandriychuk/url_shortener/controller/LinkController.java`)
- Link endpoints → Link and Base62 code: encodes code (evidence: `backend/src/main/java/com/davidandriychuk/url_shortener/controller/LinkController.java`)
- Link endpoints → Cached lookup and expiry: resolves redirect (evidence: `backend/src/main/java/com/davidandriychuk/url_shortener/controller/LinkController.java`)
- Cached lookup and expiry → Link repository: loads by id (evidence: `backend/src/main/java/com/davidandriychuk/url_shortener/service/LinkService.java`)
- Cached lookup and expiry → Link and Base62 code: decodes and checks (evidence: `backend/src/main/java/com/davidandriychuk/url_shortener/service/LinkService.java`)
- Cached lookup and expiry → Redis cache: caches lookup (evidence: `README.md`)
- Link repository → PostgreSQL: persists links (evidence: `README.md`)
- User repository → PostgreSQL: persists users (evidence: `README.md`)
- Link endpoints → RabbitMQ routing config: uses routing (evidence: `backend/src/main/java/com/davidandriychuk/url_shortener/controller/LinkController.java`)
- Link endpoints → RabbitMQ: publishes click (evidence: `backend/src/main/java/com/davidandriychuk/url_shortener/controller/LinkController.java`)
- RabbitMQ routing config → RabbitMQ: configures route
- RabbitMQ → Click event consumer: delivers event (evidence: `README.md`)
- Click event consumer → Visitor IP hashing: hashes visitor IP (evidence: `backend/src/main/java/com/davidandriychuk/url_shortener/messaging/ClickEventConsumer.java`)
- Click event consumer → Click event repository: saves click (evidence: `backend/src/main/java/com/davidandriychuk/url_shortener/messaging/ClickEventConsumer.java`)
- Click event repository → PostgreSQL: persists events (evidence: `README.md`)
