# sudhanshusingh6/tinyroute architecture

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

- Interactive diagram: https://gitdiagram.com/sudhanshusingh6/tinyroute
- Repository: https://github.com/sudhanshusingh6/tinyroute

## Overview

TinyRoute is a full-stack URL shortener: users create and manage links, visitors resolve short codes, and the system records clicks for live and historical analytics. The frontend also exposes QR codes, destination previews, and premium public bio pages; account, subscription, and rate-limit flows support those features. The graph follows documented flows and sampled service calls. Several capabilities are documented but their wiring was not sampled, so only explicitly supported links are shown.

Main entry points: [`frontend/src/hooks/useQuery.js`](https://github.com/sudhanshusingh6/tinyroute/blob/main/frontend/src/hooks/useQuery.js) (API queries), [`backend/src/main/java/com/tinyroute/analytics/service/AnalyticsEventBackgroundWorker.java`](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/analytics/service/AnalyticsEventBackgroundWorker.java) (Event worker), [`backend/src/main/java/com/tinyroute/redirect/service/RedirectService.java`](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/redirect/service/RedirectService.java) (Redirect resolver), [`backend/src/main/java/com/tinyroute/url/repository/UrlMappingRepository.java`](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/url/repository/UrlMappingRepository.java) (URL records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_spa["React app<br/>[App.jsx]"]
  node_queries["API queries<br/>[useQuery.js]"]
end

subgraph group_links["Link lifecycle"]
  node_urlctrl["URL endpoints"]
  node_urlmanage["URL management"]
  node_urlcreate["URL creation"]
  node_validation["URL validation"]
  node_redirectctrl["Redirect endpoint"]
  node_redirect["Redirect resolver"]
  node_previewctrl["Preview and QR"]
  node_preview["Preview service"]
  node_urlstore[("URL records")]
  node_cache["Redirect cache"]
end

subgraph group_identity["Identity and access"]
  node_authctrl["Auth endpoints"]
  node_auth["Authentication<br/>[AuthService.java]"]
  node_jwt["JWT handling<br/>[JwtService.java]"]
  node_refreshstore[("Refresh tokens")]
  node_ratelimit["Rate limiting"]
end

subgraph group_analytics["Click analytics"]
  node_analyticsctrl["Analytics endpoints"]
  node_analytics["Analytics queries"]
  node_redisanalytics["Live analytics"]
  node_queue["Click event queue"]
  node_worker["Event worker"]
  node_ua["User-agent parser"]
  node_geo["Geo lookup"]
  node_clickstore[("Click history")]
end

subgraph group_account["Profiles and billing"]
  node_profilectrl["Profile endpoints"]
  node_users["User service<br/>[UserService.java]"]
  node_userstore[("User records")]
  node_billingctrl["Billing endpoints"]
end

node_visitor(("Link visitor"))
node_user(("Dashboard user"))
node_redis[("Redis")]
node_postgres[("PostgreSQL")]
node_geoapi["Geo service"]

node_user -->|"uses"| node_spa
node_visitor -->|"opens short link"| node_redirectctrl
node_spa -->|"requests data"| node_queries
node_queries -->|"calls API"| node_urlctrl
node_urlctrl -->|"creates links"| node_urlcreate
node_urlctrl -->|"manages links"| node_urlmanage
node_urlcreate -->|"validates destination"| node_validation
node_urlcreate -->|"saves mapping"| node_urlstore
node_urlmanage -->|"updates mapping"| node_urlstore
node_redirectctrl -->|"resolves code"| node_redirect
node_redirect -->|"checks and warms"| node_cache
node_cache -->|"reads and writes"| node_redis
node_redirect -.->|"loads on miss"| node_urlstore
node_urlstore -->|"reads and writes"| node_postgres
node_redirect -->|"records click"| node_redisanalytics
node_redirect -->|"enqueues event"| node_queue
node_queue -->|"stores events"| node_redis
node_worker -->|"drains batches"| node_queue
node_worker -->|"parses agent"| node_ua
node_worker -->|"looks up location"| node_geo
node_geo -.->|"requests location"| node_geoapi
node_worker -->|"updates dimensions"| node_redisanalytics
node_redisanalytics -->|"stores counters"| node_redis
node_worker -->|"persists events"| node_clickstore
node_clickstore -->|"stores history"| node_postgres
node_queries -->|"requests analytics"| node_analyticsctrl
node_analyticsctrl -->|"queries reports"| node_analytics
node_analytics -->|"reads live data"| node_redisanalytics
node_analytics -->|"reads history"| node_clickstore
node_queries -->|"requests preview"| node_previewctrl
node_previewctrl -->|"gets preview or QR"| node_preview
node_preview -->|"loads mapping"| node_urlstore
node_preview -->|"loads public links"| node_userstore
node_queries -->|"requests bio"| node_profilectrl
node_profilectrl -->|"loads profile"| node_users
node_users -->|"reads and updates"| node_userstore
node_queries -->|"authenticates"| node_authctrl
node_authctrl -->|"handles account"| node_auth
node_auth -->|"issues access token"| node_jwt
node_auth -->|"rotates tokens"| node_refreshstore
node_auth -->|"reads and saves user"| node_userstore
node_ratelimit -->|"consumes buckets"| node_redis
node_queries -->|"starts billing"| node_billingctrl

click node_spa "https://github.com/sudhanshusingh6/tinyroute/blob/main/frontend/src/App.jsx"
click node_queries "https://github.com/sudhanshusingh6/tinyroute/blob/main/frontend/src/hooks/useQuery.js"
click node_urlctrl "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/url/controller/UrlCreationController.java"
click node_urlmanage "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/url/service/UrlManagementService.java"
click node_urlcreate "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/url/service/UrlCreationService.java"
click node_validation "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/url/service/UrlValidationService.java"
click node_redirectctrl "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/redirect/controller/RedirectController.java"
click node_redirect "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/redirect/service/RedirectService.java"
click node_previewctrl "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/url/controller/PreviewController.java"
click node_preview "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/url/service/UrlPreviewService.java"
click node_urlstore "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/url/repository/UrlMappingRepository.java"
click node_cache "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/infra/cache/RedirectCacheService.java"
click node_authctrl "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/auth/controller/AuthController.java"
click node_auth "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/auth/service/AuthService.java"
click node_jwt "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/security/jwt/JwtService.java"
click node_refreshstore "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/auth/repository/RefreshTokenRepository.java"
click node_ratelimit "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/ratelimit/RateLimitService.java"
click node_analyticsctrl "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/analytics/controller/AnalyticsController.java"
click node_analytics "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/analytics/service/AnalyticsService.java"
click node_redisanalytics "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/analytics/service/RedisAnalyticsService.java"
click node_queue "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/analytics/infra/RedisAnalyticsEventQueue.java"
click node_worker "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/analytics/service/AnalyticsEventBackgroundWorker.java"
click node_ua "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/analytics/infra/UserAgentParsingService.java"
click node_geo "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/analytics/infra/GeoLocationService.java"
click node_clickstore "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/analytics/repository/ClickEventRepository.java"
click node_profilectrl "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/user/controller/PublicProfileController.java"
click node_users "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/user/service/UserService.java"
click node_userstore "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/user/repository/UserRepository.java"
click node_billingctrl "https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/billing/controller/BillingController.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_spa,node_queries,node_user toneBlue
class node_urlctrl,node_urlmanage,node_urlcreate,node_validation,node_redirectctrl,node_redirect,node_previewctrl,node_preview,node_urlstore,node_cache,node_redis,node_postgres toneAmber
class node_authctrl,node_auth,node_jwt,node_refreshstore,node_ratelimit toneMint
class node_analyticsctrl,node_analytics,node_redisanalytics,node_queue,node_worker,node_ua,node_geo,node_clickstore toneRose
class node_profilectrl,node_users,node_userstore,node_billingctrl,node_visitor,node_geoapi toneIndigo
```

## Components

### Web client

- [React app](https://github.com/sudhanshusingh6/tinyroute/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API queries](https://github.com/sudhanshusingh6/tinyroute/blob/main/frontend/src/hooks/useQuery.js): `frontend/src/hooks/useQuery.js`

### Link lifecycle

- [URL endpoints](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/url/controller/UrlCreationController.java): `backend/src/main/java/com/tinyroute/url/controller/UrlCreationController.java`
- [URL management](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/url/service/UrlManagementService.java): `backend/src/main/java/com/tinyroute/url/service/UrlManagementService.java`
- [URL creation](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/url/service/UrlCreationService.java): `backend/src/main/java/com/tinyroute/url/service/UrlCreationService.java`
- [URL validation](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/url/service/UrlValidationService.java): `backend/src/main/java/com/tinyroute/url/service/UrlValidationService.java`
- [Redirect endpoint](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/redirect/controller/RedirectController.java): `backend/src/main/java/com/tinyroute/redirect/controller/RedirectController.java`
- [Redirect resolver](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/redirect/service/RedirectService.java): `backend/src/main/java/com/tinyroute/redirect/service/RedirectService.java`
- [Preview and QR](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/url/controller/PreviewController.java): `backend/src/main/java/com/tinyroute/url/controller/PreviewController.java`
- [Preview service](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/url/service/UrlPreviewService.java): `backend/src/main/java/com/tinyroute/url/service/UrlPreviewService.java`
- [URL records](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/url/repository/UrlMappingRepository.java): `backend/src/main/java/com/tinyroute/url/repository/UrlMappingRepository.java`
- [Redirect cache](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/infra/cache/RedirectCacheService.java): `backend/src/main/java/com/tinyroute/infra/cache/RedirectCacheService.java`

### Identity and access

- [Auth endpoints](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/auth/controller/AuthController.java): `backend/src/main/java/com/tinyroute/auth/controller/AuthController.java`
- [Authentication](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/auth/service/AuthService.java): `backend/src/main/java/com/tinyroute/auth/service/AuthService.java`
- [JWT handling](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/security/jwt/JwtService.java): `backend/src/main/java/com/tinyroute/security/jwt/JwtService.java`
- [Refresh tokens](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/auth/repository/RefreshTokenRepository.java): `backend/src/main/java/com/tinyroute/auth/repository/RefreshTokenRepository.java`
- [Rate limiting](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/ratelimit/RateLimitService.java): `backend/src/main/java/com/tinyroute/ratelimit/RateLimitService.java`

### Click analytics

- [Analytics endpoints](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/analytics/controller/AnalyticsController.java): `backend/src/main/java/com/tinyroute/analytics/controller/AnalyticsController.java`
- [Analytics queries](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/analytics/service/AnalyticsService.java): `backend/src/main/java/com/tinyroute/analytics/service/AnalyticsService.java`
- [Live analytics](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/analytics/service/RedisAnalyticsService.java): `backend/src/main/java/com/tinyroute/analytics/service/RedisAnalyticsService.java`
- [Click event queue](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/analytics/infra/RedisAnalyticsEventQueue.java): `backend/src/main/java/com/tinyroute/analytics/infra/RedisAnalyticsEventQueue.java`
- [Event worker](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/analytics/service/AnalyticsEventBackgroundWorker.java): `backend/src/main/java/com/tinyroute/analytics/service/AnalyticsEventBackgroundWorker.java`
- [User-agent parser](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/analytics/infra/UserAgentParsingService.java): `backend/src/main/java/com/tinyroute/analytics/infra/UserAgentParsingService.java`
- [Geo lookup](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/analytics/infra/GeoLocationService.java): `backend/src/main/java/com/tinyroute/analytics/infra/GeoLocationService.java`
- [Click history](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/analytics/repository/ClickEventRepository.java): `backend/src/main/java/com/tinyroute/analytics/repository/ClickEventRepository.java`

### Profiles and billing

- [Profile endpoints](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/user/controller/PublicProfileController.java): `backend/src/main/java/com/tinyroute/user/controller/PublicProfileController.java`
- [User service](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/user/service/UserService.java): `backend/src/main/java/com/tinyroute/user/service/UserService.java`
- [User records](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/user/repository/UserRepository.java): `backend/src/main/java/com/tinyroute/user/repository/UserRepository.java`
- [Billing endpoints](https://github.com/sudhanshusingh6/tinyroute/blob/main/backend/src/main/java/com/tinyroute/billing/controller/BillingController.java): `backend/src/main/java/com/tinyroute/billing/controller/BillingController.java`

### Other components

- **Link visitor**
- **Dashboard user**
- **Redis**
- **PostgreSQL**
- **Geo service**

## Connections

- Dashboard user → React app: uses
- Link visitor → Redirect endpoint: opens short link
- React app → API queries: requests data
- API queries → URL endpoints: calls API
- URL endpoints → URL creation: creates links
- URL endpoints → URL management: manages links
- URL creation → URL validation: validates destination
- URL creation → URL records: saves mapping
- URL management → URL records: updates mapping
- Redirect endpoint → Redirect resolver: resolves code
- Redirect resolver → Redirect cache: checks and warms
- Redirect cache → Redis: reads and writes
- Redirect resolver → URL records: loads on miss
- URL records → PostgreSQL: reads and writes
- Redirect resolver → Live analytics: records click
- Redirect resolver → Click event queue: enqueues event
- Click event queue → Redis: stores events
- Event worker → Click event queue: drains batches
- Event worker → User-agent parser: parses agent
- Event worker → Geo lookup: looks up location
- Geo lookup → Geo service: requests location
- Event worker → Live analytics: updates dimensions
- Live analytics → Redis: stores counters
- Event worker → Click history: persists events
- Click history → PostgreSQL: stores history
- API queries → Analytics endpoints: requests analytics
- Analytics endpoints → Analytics queries: queries reports
- Analytics queries → Live analytics: reads live data
- Analytics queries → Click history: reads history
- API queries → Preview and QR: requests preview
- Preview and QR → Preview service: gets preview or QR
- Preview service → URL records: loads mapping
- Preview service → User records: loads public links
- API queries → Profile endpoints: requests bio
- Profile endpoints → User service: loads profile
- User service → User records: reads and updates
- API queries → Auth endpoints: authenticates
- Auth endpoints → Authentication: handles account
- Authentication → JWT handling: issues access token
- Authentication → Refresh tokens: rotates tokens
- Authentication → User records: reads and saves user
- Rate limiting → Redis: consumes buckets
- API queries → Billing endpoints: starts billing