# raftywate/url-shortener-with-consistent-hashing architecture

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

- Interactive diagram: https://gitdiagram.com/raftywate/url-shortener-with-consistent-hashing
- Repository: https://github.com/raftywate/url-shortener-with-consistent-hashing

## Overview

ShardLink is a distributed URL-shortening demo with a React dashboard and Spring backend. Users submit a URL, the backend normalizes it, generates a Base62 code, routes it through a virtual-node consistent-hash ring, and stores the mapping; redirect requests check Redis before querying the selected logical shard. The dashboard also polls analytics and visualizes cache, redirect, shard, and ring state. Edges reflect the sampled calls and README-described flows; some dashboard widgets and analytics endpoint wiring are represented at subsystem level because their implementation was not excerpted.

Main entry points: [`frontend/src/pages/Dashboard.jsx`](https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/frontend/src/pages/Dashboard.jsx) (Dashboard), [`backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/service/UrlService.java`](https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/service/UrlService.java) (URL Service), [`backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/controller/UrlController.java`](https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/controller/UrlController.java) (URL Controller), [`frontend/src/components/ShortenCard.jsx`](https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/frontend/src/components/ShortenCard.jsx) (Shorten Form)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dashboard UI"]
  node_dashboard["Dashboard<br/>[Dashboard.jsx]"]
  node_shorten_card["Shorten Form<br/>[ShortenCard.jsx]"]
  node_analytics_widgets["Analytics Widgets<br/>[AnalyticsCards.jsx]"]
  node_stats_cards["Stats Cards<br/>[StatsCards.jsx]"]
  node_hash_ring["Hash Ring View<br/>[HashRing.jsx]"]
  node_node_controls["Node Controls<br/>[NodeControls.jsx]"]
  node_url_table["Recent URLs<br/>[UrlTable.jsx]"]
  node_redirect_chart["Redirect Chart<br/>[RedirectChart.jsx]"]
  node_url_client["URL API Client<br/>[urlService.js]"]
  node_analytics_client["Analytics Client"]
end

subgraph group_api["HTTP API"]
  node_url_controller["URL Controller<br/>[UrlController.java]"]
  node_analytics_controller["Analytics Controller"]
  node_rate_limit["Rate Limiter"]
end

subgraph group_routing["Shortening and Routing"]
  node_url_service["URL Service<br/>[UrlService.java]"]
  node_hashing["Hash Ring Router"]
  node_request_dto["URL Request<br/>[UrlRequest.java]"]
end

subgraph group_state["Storage and Metrics"]
  node_analytics["Analytics Service"]
  node_lookup_repository["Global Lookup"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
end

node_user(("User"))

node_user -->|"uses"| node_dashboard
node_dashboard -->|"renders"| node_shorten_card
node_dashboard -->|"renders"| node_analytics_widgets
node_dashboard -->|"renders"| node_stats_cards
node_dashboard -->|"renders"| node_hash_ring
node_dashboard -->|"renders"| node_node_controls
node_dashboard -->|"renders"| node_url_table
node_dashboard -->|"renders"| node_redirect_chart
node_shorten_card -->|"calls"| node_url_client
node_url_client -->|"posts URL"| node_url_controller
node_dashboard -->|"polls"| node_analytics_client
node_analytics_client -->|"requests metrics"| node_analytics_controller
node_url_controller -->|"accepts"| node_request_dto
node_url_controller -->|"checks limit"| node_rate_limit
node_url_controller -->|"delegates"| node_url_service
node_user -->|"redirects"| node_url_controller
node_analytics_controller -->|"queries"| node_analytics
node_url_service -->|"routes code"| node_hashing
node_url_service -->|"reads and saves"| node_lookup_repository
node_url_service -->|"queries shard"| node_postgres
node_url_service -->|"checks and caches"| node_redis
node_url_service -->|"updates metrics"| node_analytics
node_rate_limit -->|"counts requests"| node_redis
node_lookup_repository -.->|"persists lookup"| node_postgres

click node_dashboard "https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/frontend/src/pages/Dashboard.jsx"
click node_shorten_card "https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/frontend/src/components/ShortenCard.jsx"
click node_analytics_widgets "https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/frontend/src/components/dashboard/AnalyticsCards.jsx"
click node_stats_cards "https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/frontend/src/components/dashboard/StatsCards.jsx"
click node_hash_ring "https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/frontend/src/components/dashboard/HashRing.jsx"
click node_node_controls "https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/frontend/src/components/dashboard/NodeControls.jsx"
click node_url_table "https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/frontend/src/components/dashboard/UrlTable.jsx"
click node_redirect_chart "https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/frontend/src/components/dashboard/RedirectChart.jsx"
click node_url_client "https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/frontend/src/services/urlService.js"
click node_analytics_client "https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/frontend/src/services/analyticsService.js"
click node_url_controller "https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/controller/UrlController.java"
click node_analytics_controller "https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/controller/AnalyticsController.java"
click node_rate_limit "https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/ratelimit/RateLimitService.java"
click node_url_service "https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/service/UrlService.java"
click node_hashing "https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/hashing/ConsistentHashingService.java"
click node_request_dto "https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/dto/UrlRequest.java"
click node_analytics "https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/analytics/AnalyticsService.java"
click node_lookup_repository "https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/repository/UrlLookupRepository.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_dashboard,node_shorten_card,node_analytics_widgets,node_stats_cards,node_hash_ring,node_node_controls,node_url_table,node_redirect_chart,node_url_client,node_analytics_client,node_user toneBlue
class node_url_controller,node_analytics_controller,node_rate_limit toneAmber
class node_url_service,node_hashing,node_request_dto toneMint
class node_analytics,node_lookup_repository,node_postgres,node_redis toneRose
```

## Components

### Dashboard UI

- [Dashboard](https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Shorten Form](https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/frontend/src/components/ShortenCard.jsx): `frontend/src/components/ShortenCard.jsx`
- [Analytics Widgets](https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/frontend/src/components/dashboard/AnalyticsCards.jsx): `frontend/src/components/dashboard/AnalyticsCards.jsx`
- [Stats Cards](https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/frontend/src/components/dashboard/StatsCards.jsx): `frontend/src/components/dashboard/StatsCards.jsx`
- [Hash Ring View](https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/frontend/src/components/dashboard/HashRing.jsx): `frontend/src/components/dashboard/HashRing.jsx`
- [Node Controls](https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/frontend/src/components/dashboard/NodeControls.jsx): `frontend/src/components/dashboard/NodeControls.jsx`
- [Recent URLs](https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/frontend/src/components/dashboard/UrlTable.jsx): `frontend/src/components/dashboard/UrlTable.jsx`
- [Redirect Chart](https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/frontend/src/components/dashboard/RedirectChart.jsx): `frontend/src/components/dashboard/RedirectChart.jsx`
- [URL API Client](https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/frontend/src/services/urlService.js): `frontend/src/services/urlService.js`
- [Analytics Client](https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/frontend/src/services/analyticsService.js): `frontend/src/services/analyticsService.js`

### HTTP API

- [URL Controller](https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/controller/UrlController.java): `backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/controller/UrlController.java`
- [Analytics Controller](https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/controller/AnalyticsController.java): `backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/controller/AnalyticsController.java`
- [Rate Limiter](https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/ratelimit/RateLimitService.java): `backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/ratelimit/RateLimitService.java`

### Shortening and Routing

- [URL Service](https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/service/UrlService.java): `backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/service/UrlService.java`
- [Hash Ring Router](https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/hashing/ConsistentHashingService.java): `backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/hashing/ConsistentHashingService.java`
- [URL Request](https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/dto/UrlRequest.java): `backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/dto/UrlRequest.java`

### Storage and Metrics

- [Analytics Service](https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/analytics/AnalyticsService.java): `backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/analytics/AnalyticsService.java`
- [Global Lookup](https://github.com/raftywate/url-shortener-with-consistent-hashing/blob/main/backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/repository/UrlLookupRepository.java): `backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/repository/UrlLookupRepository.java`
- **PostgreSQL**
- **Redis**

### Other components

- **User**

## Connections

- User → Dashboard: uses (evidence: `readme.md`)
- Dashboard → Shorten Form: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → Analytics Widgets: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → Stats Cards: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → Hash Ring View: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → Node Controls: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → Recent URLs: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → Redirect Chart: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Shorten Form → URL API Client: calls (evidence: `frontend/src/components/ShortenCard.jsx`)
- URL API Client → URL Controller: posts URL (evidence: `frontend/src/services/urlService.js`)
- Dashboard → Analytics Client: polls (evidence: `frontend/src/pages/Dashboard.jsx`)
- Analytics Client → Analytics Controller: requests metrics (evidence: `frontend/src/services/analyticsService.js`)
- URL Controller → URL Request: accepts (evidence: `backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/controller/UrlController.java`)
- URL Controller → Rate Limiter: checks limit (evidence: `backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/controller/UrlController.java`)
- URL Controller → URL Service: delegates (evidence: `backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/controller/UrlController.java`)
- User → URL Controller: redirects (evidence: `readme.md`)
- Analytics Controller → Analytics Service: queries (evidence: `backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/controller/AnalyticsController.java`)
- URL Service → Hash Ring Router: routes code (evidence: `backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/service/UrlService.java`)
- URL Service → Global Lookup: reads and saves (evidence: `backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/service/UrlService.java`)
- URL Service → PostgreSQL: queries shard (evidence: `backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/service/UrlService.java`)
- URL Service → Redis: checks and caches (evidence: `backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/service/UrlService.java`)
- URL Service → Analytics Service: updates metrics (evidence: `backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/service/UrlService.java`)
- Rate Limiter → Redis: counts requests (evidence: `backend/src/main/java/org/raftywate/urlshortenerwithconsistenthashing/ratelimit/RateLimitService.java`)
- Global Lookup → PostgreSQL: persists lookup
