# koioio/short_link architecture

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

- Interactive diagram: https://gitdiagram.com/koioio/short_link
- Repository: https://github.com/koioio/short_link

## Overview

This repository contains a short-link product with a Vue frontend and a Go-Zero API/RPC architecture; the tree also includes a separate Gin-based service implementation. The principal workflow is authenticated URL submission, generation and persistence of a short code, then lookup and HTTP redirect. The graph follows the documented Go-Zero workflow and sampled handlers/service contexts; generation variants and infrastructure relationships are included where documented, though their full implementations were not sampled.

Main entry points: [`zero_remake/shorturl_rpc/internal/logic/generateshorturllogic.go`](https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_rpc/internal/logic/generateshorturllogic.go) (Generation logic), [`zero_remake/shorturl_rpc/internal/server/shorturlserver.go`](https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_rpc/internal/server/shorturlserver.go) (Short-link RPC server), [`zero_remake/shorturl_api/internal/handler/routes.go`](https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_api/internal/handler/routes.go) (Route registration), [`zero_remake/shorturl_rpc/internal/logic/handleshortlogic.go`](https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_rpc/internal/logic/handleshortlogic.go) (Redirect logic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web client"]
  node_webapp["Vue application<br/>[App.vue]"]
  node_authstate["Auth state<br/>[auth.js]"]
  node_generatepage["Generate page<br/>[Generate.vue]"]
  node_authpages["Login/register pages<br/>[Login.vue]"]
end

subgraph group_api["HTTP API"]
  node_api["HTTP gateway<br/>[shorturl.go]"]
  node_routes["Route registration<br/>[routes.go]"]
  node_generatehandler["Generate handlers<br/>[generatehandler.go]"]
  node_redirecthandler["Redirect handler<br/>[redirecthandler.go]"]
  node_authhandlers["Auth handlers<br/>[loginhandler.go]"]
  node_apictx["API service context<br/>[servicecontext.go]"]
  node_shortclient["Short-link RPC client<br/>[shorturl.go]"]
  node_userclient["User RPC client<br/>[userservice.go]"]
end

subgraph group_services["RPC services"]
  node_shortrpc["Short-link RPC server<br/>[shorturlserver.go]"]
  node_generatelogic["Generation logic"]
  node_redirectlogic["Redirect logic"]
  node_variants["Generation variants"]
  node_userserver["User RPC server"]
  node_userlogic["Login/register logic"]
  node_shortctx["Short-link service context<br/>[servicecontext.go]"]
end

subgraph group_data["Storage and generation"]
  node_mysql[("MySQL")]
  node_redis[("Redis cache")]
  node_bloom["Bloom filter"]
  node_snowflake["Snowflake IDs<br/>[mysnowflake.go]"]
  node_encoding["Base encoding<br/>[Base64.go]"]
end

node_user(("Browser user"))
node_etcd[("Etcd discovery")]

node_user -->|"uses"| node_webapp
node_webapp -->|"shows"| node_generatepage
node_webapp -->|"shows"| node_authpages
node_authpages -->|"sets token"| node_authstate
node_generatepage -->|"reads token"| node_authstate
node_generatepage -->|"submits URL"| node_api
node_authpages -->|"sends credentials"| node_api
node_api -->|"registers routes"| node_routes
node_routes -->|"dispatches"| node_generatehandler
node_routes -->|"dispatches"| node_redirecthandler
node_routes -->|"dispatches"| node_authhandlers
node_generatehandler -->|"calls RPC"| node_shortclient
node_redirecthandler -->|"calls RPC"| node_shortclient
node_authhandlers -->|"calls RPC"| node_userclient
node_apictx -->|"constructs"| node_shortclient
node_apictx -->|"constructs"| node_userclient
node_shortclient -->|"gRPC calls"| node_shortrpc
node_userclient -->|"gRPC calls"| node_userserver
node_shortrpc -->|"dispatches"| node_generatelogic
node_shortrpc -->|"dispatches"| node_redirectlogic
node_shortrpc -->|"dispatches variants"| node_variants
node_userserver -->|"dispatches"| node_userlogic
node_generatelogic -->|"generates ID"| node_snowflake
node_generatelogic -->|"encodes ID"| node_encoding
node_generatelogic -->|"checks and adds"| node_bloom
node_generatelogic -->|"reads and writes"| node_mysql
node_generatelogic -->|"caches mapping"| node_redis
node_redirectlogic -->|"checks cache"| node_redis
node_redirectlogic -->|"queries mapping"| node_mysql
node_redirectlogic -->|"refreshes cache"| node_redis
node_userlogic -->|"reads and writes"| node_mysql
node_shortctx -->|"initializes"| node_mysql
node_shortctx -->|"initializes"| node_redis
node_shortctx -->|"constructs"| node_bloom
node_api -.->|"service discovery"| node_etcd
node_shortrpc -.->|"service discovery"| node_etcd

click node_webapp "https://github.com/koioio/short_link/blob/master/web/shorturl-frontend/src/App.vue"
click node_authstate "https://github.com/koioio/short_link/blob/master/web/shorturl-frontend/src/api/auth.js"
click node_generatepage "https://github.com/koioio/short_link/blob/master/web/shorturl-frontend/src/pages/Generate.vue"
click node_authpages "https://github.com/koioio/short_link/blob/master/web/shorturl-frontend/src/pages/Login.vue"
click node_api "https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_api/shorturl.go"
click node_routes "https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_api/internal/handler/routes.go"
click node_generatehandler "https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_api/internal/handler/generatehandler.go"
click node_redirecthandler "https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_api/internal/handler/redirecthandler.go"
click node_authhandlers "https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_api/internal/handler/loginhandler.go"
click node_apictx "https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_api/internal/svc/servicecontext.go"
click node_shortclient "https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_rpc/shorturlclient/shorturl.go"
click node_userclient "https://github.com/koioio/short_link/blob/master/zero_remake/user-rpc/userservice/userservice.go"
click node_shortrpc "https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_rpc/internal/server/shorturlserver.go"
click node_generatelogic "https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_rpc/internal/logic/generateshorturllogic.go"
click node_redirectlogic "https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_rpc/internal/logic/handleshortlogic.go"
click node_variants "https://github.com/koioio/short_link/tree/master/zero_remake/shorturl_rpc/internal/logic"
click node_userserver "https://github.com/koioio/short_link/blob/master/zero_remake/user-rpc/internal/server/userserviceserver.go"
click node_userlogic "https://github.com/koioio/short_link/tree/master/zero_remake/user-rpc/internal/logic"
click node_shortctx "https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_rpc/internal/svc/servicecontext.go"
click node_bloom "https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_rpc/internal/logic/repository/RedisBloomFliter.go"
click node_snowflake "https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_rpc/internal/logic/repository/mysnowflake.go"
click node_encoding "https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_rpc/internal/logic/repository/Base64.go"

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_webapp,node_authstate,node_generatepage,node_authpages,node_user toneBlue
class node_api,node_routes,node_generatehandler,node_redirecthandler,node_authhandlers,node_apictx,node_shortclient,node_userclient,node_etcd toneAmber
class node_shortrpc,node_generatelogic,node_redirectlogic,node_variants,node_userserver,node_userlogic,node_shortctx toneMint
class node_mysql,node_redis,node_bloom,node_snowflake,node_encoding toneRose
```

## Components

### Web client

- [Vue application](https://github.com/koioio/short_link/blob/master/web/shorturl-frontend/src/App.vue): `web/shorturl-frontend/src/App.vue`
- [Auth state](https://github.com/koioio/short_link/blob/master/web/shorturl-frontend/src/api/auth.js): `web/shorturl-frontend/src/api/auth.js`
- [Generate page](https://github.com/koioio/short_link/blob/master/web/shorturl-frontend/src/pages/Generate.vue): `web/shorturl-frontend/src/pages/Generate.vue`
- [Login/register pages](https://github.com/koioio/short_link/blob/master/web/shorturl-frontend/src/pages/Login.vue): `web/shorturl-frontend/src/pages/Login.vue`

### HTTP API

- [HTTP gateway](https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_api/shorturl.go): `zero_remake/shorturl_api/shorturl.go`
- [Route registration](https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_api/internal/handler/routes.go): `zero_remake/shorturl_api/internal/handler/routes.go`
- [Generate handlers](https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_api/internal/handler/generatehandler.go): `zero_remake/shorturl_api/internal/handler/generatehandler.go`
- [Redirect handler](https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_api/internal/handler/redirecthandler.go): `zero_remake/shorturl_api/internal/handler/redirecthandler.go`
- [Auth handlers](https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_api/internal/handler/loginhandler.go): `zero_remake/shorturl_api/internal/handler/loginhandler.go`
- [API service context](https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_api/internal/svc/servicecontext.go): `zero_remake/shorturl_api/internal/svc/servicecontext.go`
- [Short-link RPC client](https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_rpc/shorturlclient/shorturl.go): `zero_remake/shorturl_rpc/shorturlclient/shorturl.go`
- [User RPC client](https://github.com/koioio/short_link/blob/master/zero_remake/user-rpc/userservice/userservice.go): `zero_remake/user-rpc/userservice/userservice.go`

### RPC services

- [Short-link RPC server](https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_rpc/internal/server/shorturlserver.go): `zero_remake/shorturl_rpc/internal/server/shorturlserver.go`
- [Generation logic](https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_rpc/internal/logic/generateshorturllogic.go): `zero_remake/shorturl_rpc/internal/logic/generateshorturllogic.go`
- [Redirect logic](https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_rpc/internal/logic/handleshortlogic.go): `zero_remake/shorturl_rpc/internal/logic/handleshortlogic.go`
- [Generation variants](https://github.com/koioio/short_link/tree/master/zero_remake/shorturl_rpc/internal/logic): `zero_remake/shorturl_rpc/internal/logic`
- [User RPC server](https://github.com/koioio/short_link/blob/master/zero_remake/user-rpc/internal/server/userserviceserver.go): `zero_remake/user-rpc/internal/server/userserviceserver.go`
- [Login/register logic](https://github.com/koioio/short_link/tree/master/zero_remake/user-rpc/internal/logic): `zero_remake/user-rpc/internal/logic`
- [Short-link service context](https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_rpc/internal/svc/servicecontext.go): `zero_remake/shorturl_rpc/internal/svc/servicecontext.go`

### Storage and generation

- **MySQL**
- **Redis cache**
- [Bloom filter](https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_rpc/internal/logic/repository/RedisBloomFliter.go): `zero_remake/shorturl_rpc/internal/logic/repository/RedisBloomFliter.go`
- [Snowflake IDs](https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_rpc/internal/logic/repository/mysnowflake.go): `zero_remake/shorturl_rpc/internal/logic/repository/mysnowflake.go`
- [Base encoding](https://github.com/koioio/short_link/blob/master/zero_remake/shorturl_rpc/internal/logic/repository/Base64.go): `zero_remake/shorturl_rpc/internal/logic/repository/Base64.go`

### Other components

- **Browser user**
- **Etcd discovery**

## Connections

- Browser user → Vue application: uses
- Vue application → Generate page: shows
- Vue application → Login/register pages: shows
- Login/register pages → Auth state: sets token
- Generate page → Auth state: reads token
- Generate page → HTTP gateway: submits URL
- Login/register pages → HTTP gateway: sends credentials
- HTTP gateway → Route registration: registers routes
- Route registration → Generate handlers: dispatches
- Route registration → Redirect handler: dispatches
- Route registration → Auth handlers: dispatches
- Generate handlers → Short-link RPC client: calls RPC
- Redirect handler → Short-link RPC client: calls RPC
- Auth handlers → User RPC client: calls RPC
- API service context → Short-link RPC client: constructs
- API service context → User RPC client: constructs
- Short-link RPC client → Short-link RPC server: gRPC calls
- User RPC client → User RPC server: gRPC calls
- Short-link RPC server → Generation logic: dispatches
- Short-link RPC server → Redirect logic: dispatches
- Short-link RPC server → Generation variants: dispatches variants
- User RPC server → Login/register logic: dispatches
- Generation logic → Snowflake IDs: generates ID
- Generation logic → Base encoding: encodes ID
- Generation logic → Bloom filter: checks and adds
- Generation logic → MySQL: reads and writes
- Generation logic → Redis cache: caches mapping
- Redirect logic → Redis cache: checks cache
- Redirect logic → MySQL: queries mapping
- Redirect logic → Redis cache: refreshes cache
- Login/register logic → MySQL: reads and writes
- Short-link service context → MySQL: initializes
- Short-link service context → Redis cache: initializes
- Short-link service context → Bloom filter: constructs
- HTTP gateway → Etcd discovery: service discovery
- Short-link RPC server → Etcd discovery: service discovery