# petruhertea/quicklink architecture

> Architecture diagram of the GitHub repository petruhertea/quicklink, 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/petruhertea/quicklink
- Repository: https://github.com/petruhertea/quicklink

## Overview

QuickLink is a URL-shortening web application. A user submits one or more URLs; the controller validates them, applies tier rules, and asks the URL service to create links. Visitors follow short codes to be redirected, while owners use dashboards and analytics. Separate branches cover OAuth identity, paid subscriptions, QR codes, expiry notices, and ad suppression. Source excerpts show controller-to-service calls and parts of OAuth and notification handling; some implementation details, including analytics persistence and payment wiring, are unsampled, so those links are omitted or marked unverified.

Main entry points: [`src/main/java/com/petruth/urlshortener/controller/ShortenUrlController.java`](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/controller/ShortenUrlController.java) (Shorten and redirect), [`src/main/java/com/petruth/urlshortener/service/ShortenedUrlServiceImpl.java`](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/ShortenedUrlServiceImpl.java) (Link operations), [`src/main/java/com/petruth/urlshortener/service/LinkExpiryNotificationService.java`](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/LinkExpiryNotificationService.java) (Expiry notices), [`src/main/java/com/petruth/urlshortener/controller/WebController.java`](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/controller/WebController.java) (Dashboard and pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_links["Links and analytics"]
  node_shorten["Shorten and redirect"]
  node_safety["URL safety"]
  node_urlservice["Link operations"]
  node_urlrepo[("Link records")]
  node_analytics["Click analytics"]
  node_clickrepo[("Click records")]
  node_qr["QR generation<br/>[QRCodeService.java]"]
  node_dashboard["Dashboard and pages<br/>[WebController.java]"]
  node_linkdto["Link request models<br/>[UrlRequest.java]"]
end

subgraph group_accounts["Accounts and access"]
  node_user["User accounts"]
  node_userrepo[("User records")]
  node_oauthflow["OAuth login"]
  node_oidcflow["OIDC login"]
  node_providerrepo[("Provider links")]
end

subgraph group_commerce["Premium and ads"]
  node_accountcontroller["Payment endpoints"]
  node_payment["Subscription service"]
  node_adfilter["Ad suppression<br/>[AdInterceptor.java]"]
end

subgraph group_engagement["Notifications and tools"]
  node_extension["Extension tokens"]
  node_notices["Expiry notices"]
  node_email["Email delivery"]
  node_notifyapi["Notification endpoints"]
end

node_visitor(("Visitor"))
node_owner(("Link owner"))
node_oauth(("OAuth providers"))
node_stripe(("Stripe"))
node_brevo(("Brevo email"))

node_owner -->|"submits links"| node_shorten
node_shorten -->|"accepts requests"| node_linkdto
node_shorten -->|"checks URLs"| node_safety
node_shorten -->|"creates links"| node_urlservice
node_shorten -->|"records clicks"| node_analytics
node_shorten -->|"requests QR"| node_qr
node_visitor -->|"opens short link"| node_shorten
node_urlservice -.->|"persists links"| node_urlrepo
node_urlservice -.->|"persists click data"| node_clickrepo
node_owner -->|"views reports"| node_dashboard
node_dashboard -->|"lists and searches"| node_urlservice
node_dashboard -->|"loads click metrics"| node_clickrepo
node_oauth -->|"authenticates"| node_oauthflow
node_oauth -->|"authenticates"| node_oidcflow
node_oauthflow -->|"finds and saves users"| node_user
node_oidcflow -->|"finds and saves users"| node_user
node_oauthflow -->|"links provider"| node_providerrepo
node_oidcflow -->|"links provider"| node_providerrepo
node_user -->|"stores accounts"| node_userrepo
node_owner -->|"manages subscription"| node_accountcontroller
node_accountcontroller -->|"handles payments"| node_payment
node_payment -.->|"creates subscription"| node_stripe
node_owner -->|"uses free tier"| node_adfilter
node_notices -->|"finds expiring links"| node_urlrepo
node_notices -->|"loads recipients"| node_userrepo
node_notices -->|"sends notices"| node_email
node_email -.->|"delivers email"| node_brevo
node_notifyapi -->|"issues tokens"| node_extension

click node_shorten "https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/controller/ShortenUrlController.java"
click node_safety "https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/UrlSafetyService.java"
click node_urlservice "https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/ShortenedUrlServiceImpl.java"
click node_urlrepo "https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/repository/ShortenedUrlRepository.java"
click node_analytics "https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/AnalyticsService.java"
click node_clickrepo "https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/repository/ClickAnalyticsRepository.java"
click node_qr "https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/QRCodeService.java"
click node_dashboard "https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/controller/WebController.java"
click node_linkdto "https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/dto/UrlRequest.java"
click node_accountcontroller "https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/controller/PaymentController.java"
click node_payment "https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/PaymentService.java"
click node_adfilter "https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/interceptor/AdInterceptor.java"
click node_user "https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/UserServiceImpl.java"
click node_userrepo "https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/repository/UserRepository.java"
click node_oauthflow "https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/CustomOAuth2UserService.java"
click node_oidcflow "https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/CustomOidcUserService.java"
click node_providerrepo "https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/repository/UserOAuthProviderRepository.java"
click node_extension "https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/ExtensionTokenService.java"
click node_notices "https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/LinkExpiryNotificationService.java"
click node_email "https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/BrevoEmailService.java"
click node_notifyapi "https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/controller/NotificationController.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_shorten,node_safety,node_urlservice,node_urlrepo,node_analytics,node_clickrepo,node_qr,node_dashboard,node_linkdto toneBlue
class node_user,node_userrepo,node_oauthflow,node_oidcflow,node_providerrepo toneAmber
class node_accountcontroller,node_payment,node_adfilter toneMint
class node_extension,node_notices,node_email,node_notifyapi toneRose
class node_visitor,node_owner,node_oauth,node_stripe,node_brevo toneIndigo
```

## Components

### Links and analytics

- [Shorten and redirect](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/controller/ShortenUrlController.java): `src/main/java/com/petruth/urlshortener/controller/ShortenUrlController.java`
- [URL safety](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/UrlSafetyService.java): `src/main/java/com/petruth/urlshortener/service/UrlSafetyService.java`
- [Link operations](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/ShortenedUrlServiceImpl.java): `src/main/java/com/petruth/urlshortener/service/ShortenedUrlServiceImpl.java`
- [Link records](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/repository/ShortenedUrlRepository.java): `src/main/java/com/petruth/urlshortener/repository/ShortenedUrlRepository.java`
- [Click analytics](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/AnalyticsService.java): `src/main/java/com/petruth/urlshortener/service/AnalyticsService.java`
- [Click records](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/repository/ClickAnalyticsRepository.java): `src/main/java/com/petruth/urlshortener/repository/ClickAnalyticsRepository.java`
- [QR generation](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/QRCodeService.java): `src/main/java/com/petruth/urlshortener/service/QRCodeService.java`
- [Dashboard and pages](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/controller/WebController.java): `src/main/java/com/petruth/urlshortener/controller/WebController.java`
- [Link request models](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/dto/UrlRequest.java): `src/main/java/com/petruth/urlshortener/dto/UrlRequest.java`

### Accounts and access

- [User accounts](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/UserServiceImpl.java): `src/main/java/com/petruth/urlshortener/service/UserServiceImpl.java`
- [User records](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/repository/UserRepository.java): `src/main/java/com/petruth/urlshortener/repository/UserRepository.java`
- [OAuth login](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/CustomOAuth2UserService.java): `src/main/java/com/petruth/urlshortener/service/CustomOAuth2UserService.java`
- [OIDC login](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/CustomOidcUserService.java): `src/main/java/com/petruth/urlshortener/service/CustomOidcUserService.java`
- [Provider links](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/repository/UserOAuthProviderRepository.java): `src/main/java/com/petruth/urlshortener/repository/UserOAuthProviderRepository.java`

### Premium and ads

- [Payment endpoints](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/controller/PaymentController.java): `src/main/java/com/petruth/urlshortener/controller/PaymentController.java`
- [Subscription service](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/PaymentService.java): `src/main/java/com/petruth/urlshortener/service/PaymentService.java`
- [Ad suppression](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/interceptor/AdInterceptor.java): `src/main/java/com/petruth/urlshortener/interceptor/AdInterceptor.java`

### Notifications and tools

- [Extension tokens](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/ExtensionTokenService.java): `src/main/java/com/petruth/urlshortener/service/ExtensionTokenService.java`
- [Expiry notices](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/LinkExpiryNotificationService.java): `src/main/java/com/petruth/urlshortener/service/LinkExpiryNotificationService.java`
- [Email delivery](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/service/BrevoEmailService.java): `src/main/java/com/petruth/urlshortener/service/BrevoEmailService.java`
- [Notification endpoints](https://github.com/petruhertea/quicklink/blob/master/src/main/java/com/petruth/urlshortener/controller/NotificationController.java): `src/main/java/com/petruth/urlshortener/controller/NotificationController.java`

### Other components

- **Visitor**
- **Link owner**
- **OAuth providers**
- **Stripe**
- **Brevo email**

## Connections

- Link owner → Shorten and redirect: submits links (evidence: `README.md`)
- Shorten and redirect → Link request models: accepts requests (evidence: `src/main/java/com/petruth/urlshortener/controller/ShortenUrlController.java`)
- Shorten and redirect → URL safety: checks URLs (evidence: `src/main/java/com/petruth/urlshortener/controller/ShortenUrlController.java`)
- Shorten and redirect → Link operations: creates links (evidence: `src/main/java/com/petruth/urlshortener/controller/ShortenUrlController.java`)
- Shorten and redirect → Click analytics: records clicks (evidence: `src/main/java/com/petruth/urlshortener/controller/ShortenUrlController.java`)
- Shorten and redirect → QR generation: requests QR (evidence: `src/main/java/com/petruth/urlshortener/controller/ShortenUrlController.java`)
- Visitor → Shorten and redirect: opens short link (evidence: `README.md`)
- Link operations → Link records: persists links (evidence: `src/main/java/com/petruth/urlshortener/service/ShortenedUrlServiceImpl.java`)
- Link operations → Click records: persists click data
- Link owner → Dashboard and pages: views reports (evidence: `README.md`)
- Dashboard and pages → Link operations: lists and searches (evidence: `src/main/java/com/petruth/urlshortener/controller/WebController.java`)
- Dashboard and pages → Click records: loads click metrics (evidence: `src/main/java/com/petruth/urlshortener/controller/WebController.java`)
- OAuth providers → OAuth login: authenticates (evidence: `src/main/java/com/petruth/urlshortener/service/CustomOAuth2UserService.java`)
- OAuth providers → OIDC login: authenticates (evidence: `src/main/java/com/petruth/urlshortener/service/CustomOidcUserService.java`)
- OAuth login → User accounts: finds and saves users (evidence: `src/main/java/com/petruth/urlshortener/service/CustomOAuth2UserService.java`)
- OIDC login → User accounts: finds and saves users (evidence: `src/main/java/com/petruth/urlshortener/service/CustomOidcUserService.java`)
- OAuth login → Provider links: links provider (evidence: `src/main/java/com/petruth/urlshortener/service/CustomOAuth2UserService.java`)
- OIDC login → Provider links: links provider (evidence: `src/main/java/com/petruth/urlshortener/service/CustomOidcUserService.java`)
- User accounts → User records: stores accounts (evidence: `src/main/java/com/petruth/urlshortener/service/UserServiceImpl.java`)
- Link owner → Payment endpoints: manages subscription (evidence: `README.md`)
- Payment endpoints → Subscription service: handles payments (evidence: `src/main/java/com/petruth/urlshortener/controller/PaymentController.java`)
- Subscription service → Stripe: creates subscription
- Link owner → Ad suppression: uses free tier (evidence: `README.md`)
- Expiry notices → Link records: finds expiring links (evidence: `src/main/java/com/petruth/urlshortener/service/LinkExpiryNotificationService.java`)
- Expiry notices → User records: loads recipients (evidence: `src/main/java/com/petruth/urlshortener/service/LinkExpiryNotificationService.java`)
- Expiry notices → Email delivery: sends notices (evidence: `src/main/java/com/petruth/urlshortener/service/LinkExpiryNotificationService.java`)
- Email delivery → Brevo email: delivers email
- Notification endpoints → Extension tokens: issues tokens (evidence: `src/main/java/com/petruth/urlshortener/controller/NotificationController.java`)
