# suraj-kumal/very-short architecture

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

- Interactive diagram: https://gitdiagram.com/suraj-kumal/very-short
- Repository: https://github.com/suraj-kumal/very-short

## Overview

This is a Go URL shortener. Users submit long URLs through the web UI or POST endpoint, receive a short link, and later use its code to redirect to the original URL. The runtime also provides expiration and error handling, static pages, concurrency limiting, cache warming, and background access-time synchronization. The README documents several flows whose handler and cache implementations were not excerpted; those links are attributed to the README rather than presented as inspected call details.

Main entry points: [`cmd/api/main.go`](https://github.com/suraj-kumal/very-short/blob/main/cmd/api/main.go) (Server bootstrap), [`internal/handlers/routes.go`](https://github.com/suraj-kumal/very-short/blob/main/internal/handlers/routes.go) (Route registration), [`internal/handlers/handlers.go`](https://github.com/suraj-kumal/very-short/blob/main/internal/handlers/handlers.go) (Request handlers), [`internal/cache/cache.go`](https://github.com/suraj-kumal/very-short/blob/main/internal/cache/cache.go) (LRU redirect cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["HTTP runtime"]
  node_main["Server bootstrap<br/>[main.go]"]
  node_routes["Route registration<br/>[routes.go]"]
  node_handler["Request handlers<br/>[handlers.go]"]
  node_limiter["Concurrency limiter"]
  node_static["Static web pages<br/>[index.html]"]
  node_errorpages["Expired and missing pages<br/>[410.html]"]
  node_longpage["Long URL page<br/>[long.html]"]
end

subgraph group_links["Link lifecycle"]
  node_encoder["Short-code encoding<br/>[encode.go]"]
end

subgraph group_state["Storage and cache"]
  node_urlrecords["URL record operations<br/>[url.go]"]
  node_dbconn["MySQL connection<br/>[database.go]"]
  node_mysql[("MySQL database")]
  node_cache[("LRU redirect cache<br/>[cache.go]")]
  node_hoturls["Hot URL loading<br/>[accesstime.go]"]
  node_accesstimes["Access-time updates<br/>[accesstime.go]"]
end

subgraph group_ops["Runtime coordination"]
  node_config["Runtime configuration<br/>[config.go]"]
  node_syncstate["Sync coordination<br/>[timesync.go]"]
end

node_visitor(("Browser or client"))

node_visitor -->|"sends requests"| node_routes
node_main -->|"loads settings"| node_config
node_main -->|"opens database"| node_dbconn
node_dbconn -->|"connects to"| node_mysql
node_main -->|"loads hot links"| node_hoturls
node_hoturls -->|"reads records"| node_mysql
node_main -->|"warms cache"| node_cache
node_main -->|"initializes sync"| node_syncstate
node_main -->|"configures handlers"| node_handler
node_main -->|"registers routes"| node_routes
node_routes -->|"dispatches requests"| node_handler
node_routes -->|"limits redirects"| node_limiter
node_routes -->|"serves assets"| node_static
node_handler -->|"generates codes"| node_encoder
node_handler -->|"stores and looks up"| node_urlrecords
node_handler -->|"checks redirects"| node_cache
node_urlrecords -->|"persists links"| node_mysql
node_handler -->|"returns error pages"| node_errorpages
node_routes -->|"serves long page"| node_longpage
node_syncstate -.->|"coordinates updates"| node_accesstimes
node_accesstimes -->|"writes timestamps"| node_mysql
node_cache -->|"synchronizes access times"| node_accesstimes

click node_main "https://github.com/suraj-kumal/very-short/blob/main/cmd/api/main.go"
click node_routes "https://github.com/suraj-kumal/very-short/blob/main/internal/handlers/routes.go"
click node_handler "https://github.com/suraj-kumal/very-short/blob/main/internal/handlers/handlers.go"
click node_limiter "https://github.com/suraj-kumal/very-short/blob/main/internal/middleware/concurrencylimit.go"
click node_static "https://github.com/suraj-kumal/very-short/blob/main/static/index.html"
click node_config "https://github.com/suraj-kumal/very-short/blob/main/internal/config/config.go"
click node_encoder "https://github.com/suraj-kumal/very-short/blob/main/internal/encode/encode.go"
click node_urlrecords "https://github.com/suraj-kumal/very-short/blob/main/internal/database/url.go"
click node_dbconn "https://github.com/suraj-kumal/very-short/blob/main/internal/database/database.go"
click node_cache "https://github.com/suraj-kumal/very-short/blob/main/internal/cache/cache.go"
click node_hoturls "https://github.com/suraj-kumal/very-short/blob/main/internal/database/accesstime.go"
click node_syncstate "https://github.com/suraj-kumal/very-short/blob/main/internal/timesync/timesync.go"
click node_accesstimes "https://github.com/suraj-kumal/very-short/blob/main/internal/database/accesstime.go"
click node_errorpages "https://github.com/suraj-kumal/very-short/blob/main/static/410.html"
click node_longpage "https://github.com/suraj-kumal/very-short/blob/main/static/long.html"

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_main,node_routes,node_handler,node_limiter,node_static,node_errorpages,node_longpage,node_visitor toneBlue
class node_encoder toneAmber
class node_urlrecords,node_dbconn,node_mysql,node_cache,node_hoturls,node_accesstimes toneMint
class node_config,node_syncstate toneRose
```

## Components

### HTTP runtime

- [Server bootstrap](https://github.com/suraj-kumal/very-short/blob/main/cmd/api/main.go): `cmd/api/main.go`
- [Route registration](https://github.com/suraj-kumal/very-short/blob/main/internal/handlers/routes.go): `internal/handlers/routes.go`
- [Request handlers](https://github.com/suraj-kumal/very-short/blob/main/internal/handlers/handlers.go): `internal/handlers/handlers.go`
- [Concurrency limiter](https://github.com/suraj-kumal/very-short/blob/main/internal/middleware/concurrencylimit.go): `internal/middleware/concurrencylimit.go`
- [Static web pages](https://github.com/suraj-kumal/very-short/blob/main/static/index.html): `static/index.html`
- [Expired and missing pages](https://github.com/suraj-kumal/very-short/blob/main/static/410.html): `static/410.html`
- [Long URL page](https://github.com/suraj-kumal/very-short/blob/main/static/long.html): `static/long.html`

### Link lifecycle

- [Short-code encoding](https://github.com/suraj-kumal/very-short/blob/main/internal/encode/encode.go): `internal/encode/encode.go`

### Storage and cache

- [URL record operations](https://github.com/suraj-kumal/very-short/blob/main/internal/database/url.go): `internal/database/url.go`
- [MySQL connection](https://github.com/suraj-kumal/very-short/blob/main/internal/database/database.go): `internal/database/database.go`
- **MySQL database**
- [LRU redirect cache](https://github.com/suraj-kumal/very-short/blob/main/internal/cache/cache.go): `internal/cache/cache.go`
- [Hot URL loading](https://github.com/suraj-kumal/very-short/blob/main/internal/database/accesstime.go): `internal/database/accesstime.go`
- [Access-time updates](https://github.com/suraj-kumal/very-short/blob/main/internal/database/accesstime.go): `internal/database/accesstime.go`

### Runtime coordination

- [Runtime configuration](https://github.com/suraj-kumal/very-short/blob/main/internal/config/config.go): `internal/config/config.go`
- [Sync coordination](https://github.com/suraj-kumal/very-short/blob/main/internal/timesync/timesync.go): `internal/timesync/timesync.go`

### Other components

- **Browser or client**

## Connections

- Browser or client → Route registration: sends requests (evidence: `README.md`)
- Server bootstrap → Runtime configuration: loads settings (evidence: `cmd/api/main.go`)
- Server bootstrap → MySQL connection: opens database (evidence: `cmd/api/main.go`)
- MySQL connection → MySQL database: connects to (evidence: `internal/database/database.go`)
- Server bootstrap → Hot URL loading: loads hot links (evidence: `cmd/api/main.go`)
- Hot URL loading → MySQL database: reads records (evidence: `internal/database/accesstime.go`)
- Server bootstrap → LRU redirect cache: warms cache (evidence: `cmd/api/main.go`)
- Server bootstrap → Sync coordination: initializes sync (evidence: `cmd/api/main.go`)
- Server bootstrap → Request handlers: configures handlers (evidence: `cmd/api/main.go`)
- Server bootstrap → Route registration: registers routes (evidence: `cmd/api/main.go`)
- Route registration → Request handlers: dispatches requests (evidence: `internal/handlers/routes.go`)
- Route registration → Concurrency limiter: limits redirects (evidence: `internal/handlers/routes.go`)
- Route registration → Static web pages: serves assets (evidence: `internal/handlers/routes.go`)
- Request handlers → Short-code encoding: generates codes (evidence: `README.md`)
- Request handlers → URL record operations: stores and looks up (evidence: `README.md`)
- Request handlers → LRU redirect cache: checks redirects (evidence: `README.md`)
- URL record operations → MySQL database: persists links (evidence: `README.md`)
- Request handlers → Expired and missing pages: returns error pages (evidence: `README.md`)
- Route registration → Long URL page: serves long page (evidence: `internal/handlers/routes.go`)
- Sync coordination → Access-time updates: coordinates updates
- Access-time updates → MySQL database: writes timestamps (evidence: `internal/database/accesstime.go`)
- LRU redirect cache → Access-time updates: synchronizes access times (evidence: `README.md`)
