# baidd1011/shortlink architecture

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

- Interactive diagram: https://gitdiagram.com/baidd1011/shortlink
- Repository: https://github.com/baidd1011/shortlink

## Overview

ShortLink is a Spring Cloud short-link platform with separate administration and core services, a gateway, and an optional aggregation mode. The main workflow is user management and link organization in admin, remote calls to project for link creation and management, then public redirects; visits are recorded asynchronously and exposed through analytics. The README documents caching, Bloom filters, distributed locks, and sharding, but the sampled sources do not show their wiring. Dashed, uncited edges mark these documented or otherwise unverified relationships; the frontend is outside the supplied source tree.

Main entry points: [`admin/src/main/java/com/qcl/shortlink/admin/controller/UserController.java`](https://github.com/baidd1011/shortlink/blob/main/admin/src/main/java/com/qcl/shortlink/admin/controller/UserController.java) (Admin API), [`project/src/main/java/com/qcl/shortlink/project/controller/ShortLinkController.java`](https://github.com/baidd1011/shortlink/blob/main/project/src/main/java/com/qcl/shortlink/project/controller/ShortLinkController.java) (Link API), [`aggregation/src/main/java/com/qcl/shortlink/aggregation/AggregationServiceApplication.java`](https://github.com/baidd1011/shortlink/blob/main/aggregation/src/main/java/com/qcl/shortlink/aggregation/AggregationServiceApplication.java) (Aggregation mode), [`admin/src/main/java/com/qcl/shortlink/admin/remote/ShortLinkRemoteService.java`](https://github.com/baidd1011/shortlink/blob/main/admin/src/main/java/com/qcl/shortlink/admin/remote/ShortLinkRemoteService.java) (Admin link operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_admin["Administration"]
  node_admin_api["Admin API"]
  node_user_service["User service<br/>[UserService.java]"]
  node_groups["Link groups<br/>[GroupService.java]"]
  node_admin_links["Admin link operations"]
  node_admin_stats["Admin analytics access"]
  node_admin_recycle["Admin recycle bin"]
end

subgraph group_core["Short-link core"]
  node_project_api["Link API"]
  node_link_service["Link operations"]
  node_redirect["Redirect handling"]
  node_title["Title lookup"]
  node_recycle["Recycle operations"]
end

subgraph group_analytics["Visit analytics"]
  node_stats_api["Stats API"]
  node_stats_service["Stats queries"]
  node_stats_events["Async stats events"]
  node_stats_store[("Stats persistence")]
end

subgraph group_platform["Platform services"]
  node_gateway["Gateway"]
  node_aggregation["Aggregation mode"]
  node_mysql[("MySQL")]
  node_redis[("Redis cache")]
end

node_user(("User"))
node_visitor(("Link visitor"))

node_user -.->|"manages account"| node_admin_api
node_admin_api -->|"delegates"| node_user_service
node_user -.->|"organizes links"| node_groups
node_user -.->|"manages links"| node_admin_links
node_admin_links -->|"calls HTTP"| node_project_api
node_admin_stats -->|"requests analytics"| node_stats_api
node_admin_recycle -.->|"calls remotely"| node_recycle
node_project_api -->|"delegates"| node_link_service
node_visitor -.->|"requests short URL"| node_redirect
node_visitor -.->|"generates visit"| node_stats_events
node_stats_api -->|"delegates"| node_stats_service
node_stats_events -.->|"persists asynchronously"| node_stats_store
node_link_service -.->|"stores links"| node_mysql
node_stats_store -.->|"uses sharded storage"| node_mysql
node_redirect -.->|"caches lookups"| node_redis
node_gateway -.->|"routes and authenticates"| node_admin_api
node_aggregation -.->|"combines services"| node_admin_api
node_aggregation -.->|"combines services"| node_project_api

click node_admin_api "https://github.com/baidd1011/shortlink/blob/main/admin/src/main/java/com/qcl/shortlink/admin/controller/UserController.java"
click node_user_service "https://github.com/baidd1011/shortlink/blob/main/admin/src/main/java/com/qcl/shortlink/admin/service/UserService.java"
click node_groups "https://github.com/baidd1011/shortlink/blob/main/admin/src/main/java/com/qcl/shortlink/admin/service/GroupService.java"
click node_admin_links "https://github.com/baidd1011/shortlink/blob/main/admin/src/main/java/com/qcl/shortlink/admin/remote/ShortLinkRemoteService.java"
click node_admin_stats "https://github.com/baidd1011/shortlink/blob/main/admin/src/main/java/com/qcl/shortlink/admin/remote/ShortLinkRemoteService.java"
click node_admin_recycle "https://github.com/baidd1011/shortlink/blob/main/admin/src/main/java/com/qcl/shortlink/admin/service/RecycleBinService.java"
click node_project_api "https://github.com/baidd1011/shortlink/blob/main/project/src/main/java/com/qcl/shortlink/project/controller/ShortLinkController.java"
click node_link_service "https://github.com/baidd1011/shortlink/blob/main/project/src/main/java/com/qcl/shortlink/project/service/ShortLinkService.java"
click node_redirect "https://github.com/baidd1011/shortlink/blob/main/project/src/main/java/com/qcl/shortlink/project/controller/ShortLinkRedirectController.java"
click node_title "https://github.com/baidd1011/shortlink/blob/main/project/src/main/java/com/qcl/shortlink/project/service/UrlTitleService.java"
click node_recycle "https://github.com/baidd1011/shortlink/blob/main/project/src/main/java/com/qcl/shortlink/project/service/RecycleBinService.java"
click node_stats_api "https://github.com/baidd1011/shortlink/blob/main/project/src/main/java/com/qcl/shortlink/project/controller/ShortLinkStatsController.java"
click node_stats_service "https://github.com/baidd1011/shortlink/blob/main/project/src/main/java/com/qcl/shortlink/project/service/ShortLinkStatsService.java"
click node_stats_events "https://github.com/baidd1011/shortlink/blob/main/project/src/main/java/com/qcl/shortlink/project/mq/producer/ShortLinkStatsSaveProducer.java"
click node_stats_store "https://github.com/baidd1011/shortlink/blob/main/project/src/main/java/com/qcl/shortlink/project/dao/entity/LinkAccessStatsDO.java"
click node_gateway "https://github.com/baidd1011/shortlink/blob/main/gateway/src/main/java/com/qcl/shortlink/gateway/filter/TokenValidateGatewayFilterFactory.java"
click node_aggregation "https://github.com/baidd1011/shortlink/blob/main/aggregation/src/main/java/com/qcl/shortlink/aggregation/AggregationServiceApplication.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_admin_api,node_user_service,node_groups,node_admin_links,node_admin_stats,node_admin_recycle,node_user toneBlue
class node_project_api,node_link_service,node_redirect,node_title,node_recycle toneAmber
class node_stats_api,node_stats_service,node_stats_events,node_stats_store toneMint
class node_gateway,node_aggregation,node_mysql,node_redis toneRose
class node_visitor toneIndigo
```

## Components

### Administration

- [Admin API](https://github.com/baidd1011/shortlink/blob/main/admin/src/main/java/com/qcl/shortlink/admin/controller/UserController.java): `admin/src/main/java/com/qcl/shortlink/admin/controller/UserController.java`
- [User service](https://github.com/baidd1011/shortlink/blob/main/admin/src/main/java/com/qcl/shortlink/admin/service/UserService.java): `admin/src/main/java/com/qcl/shortlink/admin/service/UserService.java`
- [Link groups](https://github.com/baidd1011/shortlink/blob/main/admin/src/main/java/com/qcl/shortlink/admin/service/GroupService.java): `admin/src/main/java/com/qcl/shortlink/admin/service/GroupService.java`
- [Admin link operations](https://github.com/baidd1011/shortlink/blob/main/admin/src/main/java/com/qcl/shortlink/admin/remote/ShortLinkRemoteService.java): `admin/src/main/java/com/qcl/shortlink/admin/remote/ShortLinkRemoteService.java`
- [Admin analytics access](https://github.com/baidd1011/shortlink/blob/main/admin/src/main/java/com/qcl/shortlink/admin/remote/ShortLinkRemoteService.java): `admin/src/main/java/com/qcl/shortlink/admin/remote/ShortLinkRemoteService.java`
- [Admin recycle bin](https://github.com/baidd1011/shortlink/blob/main/admin/src/main/java/com/qcl/shortlink/admin/service/RecycleBinService.java): `admin/src/main/java/com/qcl/shortlink/admin/service/RecycleBinService.java`

### Short-link core

- [Link API](https://github.com/baidd1011/shortlink/blob/main/project/src/main/java/com/qcl/shortlink/project/controller/ShortLinkController.java): `project/src/main/java/com/qcl/shortlink/project/controller/ShortLinkController.java`
- [Link operations](https://github.com/baidd1011/shortlink/blob/main/project/src/main/java/com/qcl/shortlink/project/service/ShortLinkService.java): `project/src/main/java/com/qcl/shortlink/project/service/ShortLinkService.java`
- [Redirect handling](https://github.com/baidd1011/shortlink/blob/main/project/src/main/java/com/qcl/shortlink/project/controller/ShortLinkRedirectController.java): `project/src/main/java/com/qcl/shortlink/project/controller/ShortLinkRedirectController.java`
- [Title lookup](https://github.com/baidd1011/shortlink/blob/main/project/src/main/java/com/qcl/shortlink/project/service/UrlTitleService.java): `project/src/main/java/com/qcl/shortlink/project/service/UrlTitleService.java`
- [Recycle operations](https://github.com/baidd1011/shortlink/blob/main/project/src/main/java/com/qcl/shortlink/project/service/RecycleBinService.java): `project/src/main/java/com/qcl/shortlink/project/service/RecycleBinService.java`

### Visit analytics

- [Stats API](https://github.com/baidd1011/shortlink/blob/main/project/src/main/java/com/qcl/shortlink/project/controller/ShortLinkStatsController.java): `project/src/main/java/com/qcl/shortlink/project/controller/ShortLinkStatsController.java`
- [Stats queries](https://github.com/baidd1011/shortlink/blob/main/project/src/main/java/com/qcl/shortlink/project/service/ShortLinkStatsService.java): `project/src/main/java/com/qcl/shortlink/project/service/ShortLinkStatsService.java`
- [Async stats events](https://github.com/baidd1011/shortlink/blob/main/project/src/main/java/com/qcl/shortlink/project/mq/producer/ShortLinkStatsSaveProducer.java): `project/src/main/java/com/qcl/shortlink/project/mq/producer/ShortLinkStatsSaveProducer.java`
- [Stats persistence](https://github.com/baidd1011/shortlink/blob/main/project/src/main/java/com/qcl/shortlink/project/dao/entity/LinkAccessStatsDO.java): `project/src/main/java/com/qcl/shortlink/project/dao/entity/LinkAccessStatsDO.java`

### Platform services

- [Gateway](https://github.com/baidd1011/shortlink/blob/main/gateway/src/main/java/com/qcl/shortlink/gateway/filter/TokenValidateGatewayFilterFactory.java): `gateway/src/main/java/com/qcl/shortlink/gateway/filter/TokenValidateGatewayFilterFactory.java`
- [Aggregation mode](https://github.com/baidd1011/shortlink/blob/main/aggregation/src/main/java/com/qcl/shortlink/aggregation/AggregationServiceApplication.java): `aggregation/src/main/java/com/qcl/shortlink/aggregation/AggregationServiceApplication.java`
- **MySQL**
- **Redis cache**

### Other components

- **User**
- **Link visitor**

## Connections

- User → Admin API: manages account
- Admin API → User service: delegates (evidence: `admin/src/main/java/com/qcl/shortlink/admin/controller/UserController.java`)
- User → Link groups: organizes links
- User → Admin link operations: manages links
- Admin link operations → Link API: calls HTTP (evidence: `admin/src/main/java/com/qcl/shortlink/admin/remote/ShortLinkRemoteService.java`)
- Admin analytics access → Stats API: requests analytics (evidence: `admin/src/main/java/com/qcl/shortlink/admin/remote/ShortLinkRemoteService.java`)
- Admin recycle bin → Recycle operations: calls remotely
- Link API → Link operations: delegates (evidence: `project/src/main/java/com/qcl/shortlink/project/controller/ShortLinkController.java`)
- Link visitor → Redirect handling: requests short URL
- Link visitor → Async stats events: generates visit
- Stats API → Stats queries: delegates (evidence: `project/src/main/java/com/qcl/shortlink/project/controller/ShortLinkStatsController.java`)
- Async stats events → Stats persistence: persists asynchronously
- Link operations → MySQL: stores links
- Stats persistence → MySQL: uses sharded storage
- Redirect handling → Redis cache: caches lookups
- Gateway → Admin API: routes and authenticates
- Aggregation mode → Admin API: combines services
- Aggregation mode → Link API: combines services
