# pranavnadda/url-shortner architecture

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

- Interactive diagram: https://gitdiagram.com/pranavnadda/url-shortner
- Repository: https://github.com/pranavnadda/url-shortner

## Overview

This is a URL-shortening API with owned-link management, redirects, rate limiting, and asynchronous click analytics. Its primary flow creates a validated short code, persists it, then resolves incoming codes through Caffeine, Redis, and Postgres before returning the configured redirect; active redirects offer clicks without blocking the response. The graph preserves key generation, API-key security, and analytics query/ingestion stages. Source-index references and README statements support the shown relationships; unsampled implementation details are not expanded.

Main entry points: [`src/main/java/dev/urlshortener/service/LinkService.java`](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/service/LinkService.java) (Link Service), [`src/main/java/dev/urlshortener/cache/RedirectCache.java`](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/cache/RedirectCache.java) (Layered Cache), [`src/main/java/dev/urlshortener/service/RedirectService.java`](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/service/RedirectService.java) (Redirect Service), [`src/main/java/dev/urlshortener/web/UrlController.java`](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/web/UrlController.java) (URL API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Security"]
  node_url_api["URL API<br/>[UrlController.java]"]
  node_key_api["API Key API"]
  node_auth["Key Authentication"]
  node_rate_filter["Rate Limit Filter"]
end

subgraph group_links["Link Management"]
  node_link_service["Link Service<br/>[LinkService.java]"]
  node_key_service["Key Service<br/>[ApiKeyService.java]"]
  node_code_generation["Code Generation<br/>[FeistelCodec.java]"]
  node_id_lease["ID Leasing"]
  node_link_record["Link Records<br/>[LinkRecord.java]"]
end

subgraph group_redirect["Redirect Resolution"]
  node_redirect_api["Redirect Endpoint"]
  node_redirect_service["Redirect Service"]
  node_redirect_cache["Layered Cache<br/>[RedirectCache.java]"]
end

subgraph group_analytics["Click Analytics"]
  node_click_publisher["Click Publisher"]
  node_event_broker["Redpanda"]
  node_click_consumer["Click Consumer<br/>[ClickConsumer.java]"]
  node_clickhouse_store["ClickHouse Store"]
  node_clickhouse[("ClickHouse")]
  node_analytics_service["Analytics Queries"]
end

subgraph group_platform["State and Infrastructure"]
  node_caffeine[("Caffeine Cache")]
  node_redis_cache[("Redis Cache")]
  node_link_store[("Link Store<br/>[JdbcLinkStore.java]")]
  node_key_store[("API Key Store")]
  node_postgres[("Postgres")]
  node_metrics["Application Metrics<br/>[AppMetrics.java]"]
end

node_client(("API Client"))

node_client -->|"manages links"| node_url_api
node_client -->|"requests short URL"| node_redirect_api
node_client -->|"creates key"| node_key_api
node_url_api -->|"delegates"| node_link_service
node_url_api -->|"queries analytics"| node_analytics_service
node_key_api -->|"delegates"| node_key_service
node_auth -->|"validates key"| node_key_store
node_auth -.->|"rate limits API"| node_rate_filter
node_client -->|"rate limited"| node_rate_filter
node_link_service -->|"encodes ID"| node_code_generation
node_link_service -->|"allocates IDs"| node_id_lease
node_link_service -->|"persists links"| node_link_store
node_link_service -->|"invalidates entries"| node_redirect_cache
node_link_service -->|"creates records"| node_link_record
node_code_generation -.->|"transforms IDs"| node_id_lease
node_redirect_api -->|"delegates"| node_redirect_service
node_redirect_service -->|"resolves code"| node_redirect_cache
node_redirect_cache -->|"checks first"| node_caffeine
node_redirect_cache -->|"checks next"| node_redis_cache
node_redirect_cache -->|"loads on miss"| node_link_store
node_link_store -->|"reads and writes"| node_postgres
node_redirect_service -->|"offers click"| node_click_publisher
node_click_publisher -->|"publishes events"| node_event_broker
node_event_broker -->|"delivers events"| node_click_consumer
node_click_consumer -->|"writes batches"| node_clickhouse_store
node_clickhouse_store -->|"stores events"| node_clickhouse
node_analytics_service -->|"queries counts"| node_clickhouse_store
node_click_consumer -->|"records lag"| node_metrics
node_redirect_service -->|"records redirects"| node_metrics

click node_url_api "https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/web/UrlController.java"
click node_key_api "https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/web/ApiKeyController.java"
click node_auth "https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/auth/ApiKeyAuthFilter.java"
click node_rate_filter "https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/ratelimit/RateLimitFilter.java"
click node_link_service "https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/service/LinkService.java"
click node_key_service "https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/service/ApiKeyService.java"
click node_code_generation "https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/codec/FeistelCodec.java"
click node_id_lease "https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/lease/IdBlockAllocator.java"
click node_link_record "https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/domain/LinkRecord.java"
click node_redirect_api "https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/web/RedirectController.java"
click node_redirect_service "https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/service/RedirectService.java"
click node_redirect_cache "https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/cache/RedirectCache.java"
click node_caffeine "https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/cache/CaffeineLayerCache.java"
click node_redis_cache "https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/cache/RedisLayerCache.java"
click node_link_store "https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/store/JdbcLinkStore.java"
click node_key_store "https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/store/JdbcApiKeyStore.java"
click node_click_publisher "https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/analytics/ClickPublisher.java"
click node_click_consumer "https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/analytics/ClickConsumer.java"
click node_clickhouse_store "https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/analytics/ClickHouseStore.java"
click node_analytics_service "https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/service/AnalyticsService.java"
click node_metrics "https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/metrics/AppMetrics.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_url_api,node_key_api,node_auth,node_rate_filter,node_client toneBlue
class node_link_service,node_key_service,node_code_generation,node_id_lease,node_link_record toneAmber
class node_redirect_api,node_redirect_service,node_redirect_cache toneMint
class node_click_publisher,node_event_broker,node_click_consumer,node_clickhouse_store,node_clickhouse,node_analytics_service toneRose
class node_caffeine,node_redis_cache,node_link_store,node_key_store,node_postgres,node_metrics toneIndigo
```

## Components

### API and Security

- [URL API](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/web/UrlController.java): `src/main/java/dev/urlshortener/web/UrlController.java`
- [API Key API](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/web/ApiKeyController.java): `src/main/java/dev/urlshortener/web/ApiKeyController.java`
- [Key Authentication](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/auth/ApiKeyAuthFilter.java): `src/main/java/dev/urlshortener/auth/ApiKeyAuthFilter.java`
- [Rate Limit Filter](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/ratelimit/RateLimitFilter.java): `src/main/java/dev/urlshortener/ratelimit/RateLimitFilter.java`

### Link Management

- [Link Service](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/service/LinkService.java): `src/main/java/dev/urlshortener/service/LinkService.java`
- [Key Service](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/service/ApiKeyService.java): `src/main/java/dev/urlshortener/service/ApiKeyService.java`
- [Code Generation](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/codec/FeistelCodec.java): `src/main/java/dev/urlshortener/codec/FeistelCodec.java`
- [ID Leasing](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/lease/IdBlockAllocator.java): `src/main/java/dev/urlshortener/lease/IdBlockAllocator.java`
- [Link Records](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/domain/LinkRecord.java): `src/main/java/dev/urlshortener/domain/LinkRecord.java`

### Redirect Resolution

- [Redirect Endpoint](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/web/RedirectController.java): `src/main/java/dev/urlshortener/web/RedirectController.java`
- [Redirect Service](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/service/RedirectService.java): `src/main/java/dev/urlshortener/service/RedirectService.java`
- [Layered Cache](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/cache/RedirectCache.java): `src/main/java/dev/urlshortener/cache/RedirectCache.java`

### Click Analytics

- [Click Publisher](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/analytics/ClickPublisher.java): `src/main/java/dev/urlshortener/analytics/ClickPublisher.java`
- **Redpanda**
- [Click Consumer](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/analytics/ClickConsumer.java): `src/main/java/dev/urlshortener/analytics/ClickConsumer.java`
- [ClickHouse Store](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/analytics/ClickHouseStore.java): `src/main/java/dev/urlshortener/analytics/ClickHouseStore.java`
- **ClickHouse**
- [Analytics Queries](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/service/AnalyticsService.java): `src/main/java/dev/urlshortener/service/AnalyticsService.java`

### State and Infrastructure

- [Caffeine Cache](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/cache/CaffeineLayerCache.java): `src/main/java/dev/urlshortener/cache/CaffeineLayerCache.java`
- [Redis Cache](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/cache/RedisLayerCache.java): `src/main/java/dev/urlshortener/cache/RedisLayerCache.java`
- [Link Store](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/store/JdbcLinkStore.java): `src/main/java/dev/urlshortener/store/JdbcLinkStore.java`
- [API Key Store](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/store/JdbcApiKeyStore.java): `src/main/java/dev/urlshortener/store/JdbcApiKeyStore.java`
- **Postgres**
- [Application Metrics](https://github.com/pranavnadda/url-shortner/blob/main/src/main/java/dev/urlshortener/metrics/AppMetrics.java): `src/main/java/dev/urlshortener/metrics/AppMetrics.java`

### Other components

- **API Client**

## Connections

- API Client → URL API: manages links (evidence: `src/main/java/dev/urlshortener/web/UrlController.java`)
- API Client → Redirect Endpoint: requests short URL (evidence: `README.md`)
- API Client → API Key API: creates key (evidence: `README.md`)
- URL API → Link Service: delegates (evidence: `src/main/java/dev/urlshortener/web/UrlController.java`)
- URL API → Analytics Queries: queries analytics (evidence: `src/main/java/dev/urlshortener/web/UrlController.java`)
- API Key API → Key Service: delegates (evidence: `src/main/java/dev/urlshortener/web/ApiKeyController.java`)
- Key Authentication → API Key Store: validates key (evidence: `src/main/java/dev/urlshortener/auth/ApiKeyAuthFilter.java`)
- Key Authentication → Rate Limit Filter: rate limits API
- API Client → Rate Limit Filter: rate limited (evidence: `README.md`)
- Link Service → Code Generation: encodes ID (evidence: `src/main/java/dev/urlshortener/service/LinkService.java`)
- Link Service → ID Leasing: allocates IDs (evidence: `src/main/java/dev/urlshortener/service/LinkService.java`)
- Link Service → Link Store: persists links (evidence: `src/main/java/dev/urlshortener/service/LinkService.java`)
- Link Service → Layered Cache: invalidates entries (evidence: `src/main/java/dev/urlshortener/service/LinkService.java`)
- Link Service → Link Records: creates records (evidence: `src/main/java/dev/urlshortener/service/LinkService.java`)
- Code Generation → ID Leasing: transforms IDs
- Redirect Endpoint → Redirect Service: delegates (evidence: `src/main/java/dev/urlshortener/web/RedirectController.java`)
- Redirect Service → Layered Cache: resolves code (evidence: `src/main/java/dev/urlshortener/service/RedirectService.java`)
- Layered Cache → Caffeine Cache: checks first (evidence: `README.md`)
- Layered Cache → Redis Cache: checks next (evidence: `README.md`)
- Layered Cache → Link Store: loads on miss (evidence: `README.md`)
- Link Store → Postgres: reads and writes (evidence: `README.md`)
- Redirect Service → Click Publisher: offers click (evidence: `src/main/java/dev/urlshortener/service/RedirectService.java`)
- Click Publisher → Redpanda: publishes events (evidence: `README.md`)
- Redpanda → Click Consumer: delivers events (evidence: `README.md`)
- Click Consumer → ClickHouse Store: writes batches (evidence: `src/main/java/dev/urlshortener/analytics/ClickConsumer.java`)
- ClickHouse Store → ClickHouse: stores events (evidence: `README.md`)
- Analytics Queries → ClickHouse Store: queries counts (evidence: `src/main/java/dev/urlshortener/service/AnalyticsService.java`)
- Click Consumer → Application Metrics: records lag (evidence: `src/main/java/dev/urlshortener/analytics/ClickConsumer.java`)
- Redirect Service → Application Metrics: records redirects (evidence: `src/main/java/dev/urlshortener/service/RedirectService.java`)
