# say-boop/shortlink architecture

> Architecture diagram of the GitHub repository say-boop/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/say-boop/shortlink
- Repository: https://github.com/say-boop/shortlink

## Overview

ShortLink is a FastAPI service for authenticated link management and public redirects. Users register or log in, create and manage short links, and visitors follow codes to reach the original URL while click activity is recorded for statistics. Separate branches cover accounts, tags, and link analytics/export. The repository also includes Celery configuration and documents expiry notifications, but the sampled material does not show task dispatch or notification delivery, so those connections are left unasserted.

Main entry points: [`app/routers/links.py`](https://github.com/say-boop/shortlink/blob/main/app/routers/links.py) (Link endpoints), [`app/routers/auth.py`](https://github.com/say-boop/shortlink/blob/main/app/routers/auth.py) (Account endpoints), [`app/database.py`](https://github.com/say-boop/shortlink/blob/main/app/database.py) (SQL database), [`app/dependencies.py`](https://github.com/say-boop/shortlink/blob/main/app/dependencies.py) (Token user lookup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API workflows"]
  node_api["FastAPI application<br/>[main.py]"]
  node_link_api["Link endpoints<br/>[links.py]"]
  node_tag_api["Tag endpoints<br/>[tags.py]"]
end

subgraph group_identity["Identity and profiles"]
  node_auth_api["Account endpoints<br/>[auth.py]"]
  node_auth_helpers["Auth helpers<br/>[auth.py]"]
  node_auth_guard["Token user lookup<br/>[dependencies.py]"]
  node_user_schema["User schemas<br/>[user.py]"]
end

subgraph group_linkdata["Link and activity data"]
  node_user_model["User records<br/>[user.py]"]
  node_link_schema["Link schemas<br/>[link.py]"]
  node_tag_schema["Tag schemas<br/>[tag.py]"]
  node_link_model["Link records<br/>[link.py]"]
  node_tag_model["Tag records<br/>[tag.py]"]
  node_click_model["Click records<br/>[click_log.py]"]
  node_shortcode["Short-code logic<br/>[shortcode.py]"]
  node_preview["Link previews<br/>[preview.py]"]
  node_geoip["Country lookup<br/>[geoip.py]"]
  node_device["Device lookup<br/>[device.py]"]
end

subgraph group_runtime["Runtime services"]
  node_database[("SQL database<br/>[database.py]")]
  node_redis[("Redis cache<br/>[redis_client.py]")]
  node_celery["Background tasks<br/>[celery_app.py]"]
end

node_visitor(("Link visitor"))
node_user(("Account user"))

node_api -->|"registers routes"| node_link_api
node_api -->|"registers routes"| node_auth_api
node_api -->|"registers routes"| node_tag_api
node_user -.->|"uses account API"| node_auth_api
node_visitor -.->|"requests redirect"| node_link_api
node_auth_api -->|"queries and updates"| node_database
node_auth_api -->|"hashes and verifies"| node_auth_helpers
node_auth_api -->|"requires current user"| node_auth_guard
node_auth_api -->|"stores tokens"| node_redis
node_auth_api -->|"validates responses"| node_user_schema
node_auth_guard -->|"loads user"| node_database
node_auth_guard -->|"verifies token"| node_auth_helpers
node_auth_guard -->|"queries user"| node_user_model
node_link_api -->|"queries and updates"| node_database
node_link_api -->|"requires current user"| node_auth_guard
node_link_api -->|"validates link data"| node_link_schema
node_link_api -->|"reads and writes"| node_link_model
node_link_api -->|"checks cached URL"| node_redis
node_link_api -->|"generates codes"| node_shortcode
node_link_api -->|"gets link title"| node_preview
node_link_api -->|"looks up country"| node_geoip
node_link_api -->|"detects device"| node_device
node_link_api -->|"records clicks"| node_click_model
node_link_api -->|"attaches tags"| node_tag_model
node_tag_api -->|"queries and updates"| node_database
node_tag_api -->|"requires current user"| node_auth_guard
node_tag_api -->|"reads and writes"| node_tag_model
node_tag_api -->|"validates responses"| node_tag_schema
node_database -->|"registers model"| node_link_model
node_database -->|"registers model"| node_user_model
node_link_model -->|"associates tags"| node_tag_model
node_celery -->|"uses database"| node_database

click node_api "https://github.com/say-boop/shortlink/blob/main/app/main.py"
click node_link_api "https://github.com/say-boop/shortlink/blob/main/app/routers/links.py"
click node_tag_api "https://github.com/say-boop/shortlink/blob/main/app/routers/tags.py"
click node_auth_api "https://github.com/say-boop/shortlink/blob/main/app/routers/auth.py"
click node_auth_helpers "https://github.com/say-boop/shortlink/blob/main/app/services/auth.py"
click node_auth_guard "https://github.com/say-boop/shortlink/blob/main/app/dependencies.py"
click node_user_schema "https://github.com/say-boop/shortlink/blob/main/app/schemas/user.py"
click node_user_model "https://github.com/say-boop/shortlink/blob/main/app/models/user.py"
click node_link_schema "https://github.com/say-boop/shortlink/blob/main/app/schemas/link.py"
click node_tag_schema "https://github.com/say-boop/shortlink/blob/main/app/schemas/tag.py"
click node_link_model "https://github.com/say-boop/shortlink/blob/main/app/models/link.py"
click node_tag_model "https://github.com/say-boop/shortlink/blob/main/app/models/tag.py"
click node_click_model "https://github.com/say-boop/shortlink/blob/main/app/models/click_log.py"
click node_database "https://github.com/say-boop/shortlink/blob/main/app/database.py"
click node_redis "https://github.com/say-boop/shortlink/blob/main/app/cache/redis_client.py"
click node_shortcode "https://github.com/say-boop/shortlink/blob/main/app/services/shortcode.py"
click node_preview "https://github.com/say-boop/shortlink/blob/main/app/services/preview.py"
click node_geoip "https://github.com/say-boop/shortlink/blob/main/app/services/geoip.py"
click node_device "https://github.com/say-boop/shortlink/blob/main/app/services/device.py"
click node_celery "https://github.com/say-boop/shortlink/blob/main/app/celery_app.py"

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_api,node_link_api,node_tag_api,node_user toneBlue
class node_auth_api,node_auth_helpers,node_auth_guard,node_user_schema toneAmber
class node_user_model,node_link_schema,node_tag_schema,node_link_model,node_tag_model,node_click_model,node_shortcode,node_preview,node_geoip,node_device toneMint
class node_database,node_redis,node_celery toneRose
class node_visitor toneIndigo
```

## Components

### API workflows

- [FastAPI application](https://github.com/say-boop/shortlink/blob/main/app/main.py): `app/main.py`
- [Link endpoints](https://github.com/say-boop/shortlink/blob/main/app/routers/links.py): `app/routers/links.py`
- [Tag endpoints](https://github.com/say-boop/shortlink/blob/main/app/routers/tags.py): `app/routers/tags.py`

### Identity and profiles

- [Account endpoints](https://github.com/say-boop/shortlink/blob/main/app/routers/auth.py): `app/routers/auth.py`
- [Auth helpers](https://github.com/say-boop/shortlink/blob/main/app/services/auth.py): `app/services/auth.py`
- [Token user lookup](https://github.com/say-boop/shortlink/blob/main/app/dependencies.py): `app/dependencies.py`
- [User schemas](https://github.com/say-boop/shortlink/blob/main/app/schemas/user.py): `app/schemas/user.py`

### Link and activity data

- [User records](https://github.com/say-boop/shortlink/blob/main/app/models/user.py): `app/models/user.py`
- [Link schemas](https://github.com/say-boop/shortlink/blob/main/app/schemas/link.py): `app/schemas/link.py`
- [Tag schemas](https://github.com/say-boop/shortlink/blob/main/app/schemas/tag.py): `app/schemas/tag.py`
- [Link records](https://github.com/say-boop/shortlink/blob/main/app/models/link.py): `app/models/link.py`
- [Tag records](https://github.com/say-boop/shortlink/blob/main/app/models/tag.py): `app/models/tag.py`
- [Click records](https://github.com/say-boop/shortlink/blob/main/app/models/click_log.py): `app/models/click_log.py`
- [Short-code logic](https://github.com/say-boop/shortlink/blob/main/app/services/shortcode.py): `app/services/shortcode.py`
- [Link previews](https://github.com/say-boop/shortlink/blob/main/app/services/preview.py): `app/services/preview.py`
- [Country lookup](https://github.com/say-boop/shortlink/blob/main/app/services/geoip.py): `app/services/geoip.py`
- [Device lookup](https://github.com/say-boop/shortlink/blob/main/app/services/device.py): `app/services/device.py`

### Runtime services

- [SQL database](https://github.com/say-boop/shortlink/blob/main/app/database.py): `app/database.py`
- [Redis cache](https://github.com/say-boop/shortlink/blob/main/app/cache/redis_client.py): `app/cache/redis_client.py`
- [Background tasks](https://github.com/say-boop/shortlink/blob/main/app/celery_app.py): `app/celery_app.py`

### Other components

- **Link visitor**
- **Account user**

## Connections

- FastAPI application → Link endpoints: registers routes (evidence: `app/main.py`)
- FastAPI application → Account endpoints: registers routes (evidence: `app/main.py`)
- FastAPI application → Tag endpoints: registers routes (evidence: `app/main.py`)
- Account user → Account endpoints: uses account API (evidence: `README.md`)
- Link visitor → Link endpoints: requests redirect (evidence: `README.md`)
- Account endpoints → SQL database: queries and updates (evidence: `app/routers/auth.py`)
- Account endpoints → Auth helpers: hashes and verifies (evidence: `app/routers/auth.py`)
- Account endpoints → Token user lookup: requires current user (evidence: `app/routers/auth.py`)
- Account endpoints → Redis cache: stores tokens (evidence: `app/routers/auth.py`)
- Account endpoints → User schemas: validates responses (evidence: `app/routers/auth.py`)
- Token user lookup → SQL database: loads user (evidence: `app/dependencies.py`)
- Token user lookup → Auth helpers: verifies token (evidence: `app/dependencies.py`)
- Token user lookup → User records: queries user (evidence: `app/dependencies.py`)
- Link endpoints → SQL database: queries and updates (evidence: `app/routers/links.py`)
- Link endpoints → Token user lookup: requires current user (evidence: `app/routers/links.py`)
- Link endpoints → Link schemas: validates link data (evidence: `app/routers/links.py`)
- Link endpoints → Link records: reads and writes (evidence: `app/routers/links.py`)
- Link endpoints → Redis cache: checks cached URL (evidence: `app/routers/links.py`)
- Link endpoints → Short-code logic: generates codes (evidence: `app/routers/links.py`)
- Link endpoints → Link previews: gets link title (evidence: `app/routers/links.py`)
- Link endpoints → Country lookup: looks up country (evidence: `app/routers/links.py`)
- Link endpoints → Device lookup: detects device (evidence: `app/routers/links.py`)
- Link endpoints → Click records: records clicks (evidence: `app/routers/links.py`)
- Link endpoints → Tag records: attaches tags (evidence: `app/routers/links.py`)
- Tag endpoints → SQL database: queries and updates (evidence: `app/routers/tags.py`)
- Tag endpoints → Token user lookup: requires current user (evidence: `app/routers/tags.py`)
- Tag endpoints → Tag records: reads and writes (evidence: `app/routers/tags.py`)
- Tag endpoints → Tag schemas: validates responses (evidence: `app/routers/tags.py`)
- SQL database → Link records: registers model (evidence: `app/database.py`)
- SQL database → User records: registers model (evidence: `app/database.py`)
- Link records → Tag records: associates tags (evidence: `app/models/link.py`)
- Background tasks → SQL database: uses database (evidence: `app/celery_app.py`)
