# onlyarchanos/url-shortener architecture

> Architecture diagram of the GitHub repository onlyarchanos/url-shortener, 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/onlyarchanos/url-shortener
- Repository: https://github.com/onlyarchanos/url-shortener

## Overview

This is a local URL-shortening product with both a command-line interface and a Flask API. Users create links with generated Base62 codes or custom aliases, then resolve, list, inspect, or delete them. The API adds accounts and API-key authentication, expiry, rate limiting, per-link statistics, and an analytics page. Shared URL, account, and persistence logic lives in database.py. The excerpts show direct calls between the entry points and that shared logic; some endpoint details are documented only in the README.

Main entry points: [`database.py`](https://github.com/onlyarchanos/url-shortener/blob/master/database.py) (SQLite database), [`main.py`](https://github.com/onlyarchanos/url-shortener/blob/master/main.py) (CLI commands), [`app.py`](https://github.com/onlyarchanos/url-shortener/blob/master/app.py) (Shorten endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User interfaces"]
  node_cli["CLI commands<br/>[main.py]"]
end

subgraph group_web["Web API"]
  node_web_routes["Flask routes<br/>[app.py]"]
  node_rate_limit["Rate limiter<br/>[app.py]"]
  node_web_accounts["Registration and login<br/>[app.py]"]
  node_web_shorten["Shorten endpoint<br/>[app.py]"]
  node_web_redirect["Redirect endpoint<br/>[app.py]"]
  node_web_manage["Stats and deletion<br/>[app.py]"]
  node_web_analytics["Analytics page<br/>[app.py]"]
end

subgraph group_domain["Shared domain logic"]
  node_url_validation["URL and alias validation<br/>[database.py]"]
  node_code_generation["Base62 code generation<br/>[database.py]"]
  node_url_records["URL record operations<br/>[database.py]"]
  node_expiry["Expiry checks<br/>[database.py]"]
  node_account_logic["Account and API keys<br/>[database.py]"]
  node_click_tracking["Click tracking<br/>[database.py]"]
  node_analytics_query["Top-link query<br/>[database.py]"]
end

subgraph group_storage["Persistence"]
  node_sqlite[("SQLite database<br/>[database.py]")]
end

node_cli_user(("CLI user"))
node_api_client(("API client"))

node_cli_user -->|"runs commands"| node_cli
node_api_client -->|"sends requests"| node_web_routes
node_cli -->|"validates links"| node_url_validation
node_cli -->|"gets code"| node_code_generation
node_cli -->|"manages links"| node_url_records
node_web_routes -.->|"checks limits"| node_rate_limit
node_web_accounts -->|"registers and authenticates"| node_account_logic
node_web_shorten -->|"validates input"| node_url_validation
node_web_shorten -->|"gets code"| node_code_generation
node_web_shorten -->|"saves link"| node_url_records
node_web_redirect -->|"looks up link"| node_url_records
node_web_redirect -->|"checks expiry"| node_expiry
node_web_manage -->|"authenticates user"| node_account_logic
node_web_manage -->|"reads and deletes"| node_url_records
node_web_analytics -->|"authenticates user"| node_account_logic
node_web_analytics -->|"requests top links"| node_analytics_query
node_url_validation -->|"checks aliases"| node_sqlite
node_code_generation -->|"updates counter"| node_sqlite
node_url_records -->|"reads and writes"| node_sqlite
node_account_logic -->|"reads and writes"| node_sqlite
node_click_tracking -->|"updates clicks"| node_sqlite
node_analytics_query -->|"queries links"| node_sqlite

click node_cli "https://github.com/onlyarchanos/url-shortener/blob/master/main.py"
click node_web_routes "https://github.com/onlyarchanos/url-shortener/blob/master/app.py"
click node_rate_limit "https://github.com/onlyarchanos/url-shortener/blob/master/app.py"
click node_web_accounts "https://github.com/onlyarchanos/url-shortener/blob/master/app.py"
click node_web_shorten "https://github.com/onlyarchanos/url-shortener/blob/master/app.py"
click node_web_redirect "https://github.com/onlyarchanos/url-shortener/blob/master/app.py"
click node_web_manage "https://github.com/onlyarchanos/url-shortener/blob/master/app.py"
click node_web_analytics "https://github.com/onlyarchanos/url-shortener/blob/master/app.py"
click node_url_validation "https://github.com/onlyarchanos/url-shortener/blob/master/database.py"
click node_code_generation "https://github.com/onlyarchanos/url-shortener/blob/master/database.py"
click node_url_records "https://github.com/onlyarchanos/url-shortener/blob/master/database.py"
click node_expiry "https://github.com/onlyarchanos/url-shortener/blob/master/database.py"
click node_account_logic "https://github.com/onlyarchanos/url-shortener/blob/master/database.py"
click node_click_tracking "https://github.com/onlyarchanos/url-shortener/blob/master/database.py"
click node_analytics_query "https://github.com/onlyarchanos/url-shortener/blob/master/database.py"
click node_sqlite "https://github.com/onlyarchanos/url-shortener/blob/master/database.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_cli,node_cli_user,node_api_client toneBlue
class node_web_routes,node_rate_limit,node_web_accounts,node_web_shorten,node_web_redirect,node_web_manage,node_web_analytics toneAmber
class node_url_validation,node_code_generation,node_url_records,node_expiry,node_account_logic,node_click_tracking,node_analytics_query toneMint
class node_sqlite toneRose
```

## Components

### User interfaces

- [CLI commands](https://github.com/onlyarchanos/url-shortener/blob/master/main.py): `main.py`

### Web API

- [Flask routes](https://github.com/onlyarchanos/url-shortener/blob/master/app.py): `app.py`
- [Rate limiter](https://github.com/onlyarchanos/url-shortener/blob/master/app.py): `app.py`
- [Registration and login](https://github.com/onlyarchanos/url-shortener/blob/master/app.py): `app.py`
- [Shorten endpoint](https://github.com/onlyarchanos/url-shortener/blob/master/app.py): `app.py`
- [Redirect endpoint](https://github.com/onlyarchanos/url-shortener/blob/master/app.py): `app.py`
- [Stats and deletion](https://github.com/onlyarchanos/url-shortener/blob/master/app.py): `app.py`
- [Analytics page](https://github.com/onlyarchanos/url-shortener/blob/master/app.py): `app.py`

### Shared domain logic

- [URL and alias validation](https://github.com/onlyarchanos/url-shortener/blob/master/database.py): `database.py`
- [Base62 code generation](https://github.com/onlyarchanos/url-shortener/blob/master/database.py): `database.py`
- [URL record operations](https://github.com/onlyarchanos/url-shortener/blob/master/database.py): `database.py`
- [Expiry checks](https://github.com/onlyarchanos/url-shortener/blob/master/database.py): `database.py`
- [Account and API keys](https://github.com/onlyarchanos/url-shortener/blob/master/database.py): `database.py`
- [Click tracking](https://github.com/onlyarchanos/url-shortener/blob/master/database.py): `database.py`
- [Top-link query](https://github.com/onlyarchanos/url-shortener/blob/master/database.py): `database.py`

### Persistence

- [SQLite database](https://github.com/onlyarchanos/url-shortener/blob/master/database.py): `database.py`

### Other components

- **CLI user**
- **API client**

## Connections

- CLI user → CLI commands: runs commands (evidence: `README.md`)
- API client → Flask routes: sends requests (evidence: `README.md`)
- CLI commands → URL and alias validation: validates links (evidence: `main.py`)
- CLI commands → Base62 code generation: gets code (evidence: `main.py`)
- CLI commands → URL record operations: manages links (evidence: `main.py`)
- Flask routes → Rate limiter: checks limits (evidence: `app.py`)
- Registration and login → Account and API keys: registers and authenticates (evidence: `app.py`)
- Shorten endpoint → URL and alias validation: validates input (evidence: `app.py`)
- Shorten endpoint → Base62 code generation: gets code (evidence: `app.py`)
- Shorten endpoint → URL record operations: saves link (evidence: `app.py`)
- Redirect endpoint → URL record operations: looks up link (evidence: `app.py`)
- Redirect endpoint → Expiry checks: checks expiry (evidence: `app.py`)
- Stats and deletion → Account and API keys: authenticates user (evidence: `app.py`)
- Stats and deletion → URL record operations: reads and deletes (evidence: `app.py`)
- Analytics page → Account and API keys: authenticates user (evidence: `app.py`)
- Analytics page → Top-link query: requests top links (evidence: `app.py`)
- URL and alias validation → SQLite database: checks aliases (evidence: `database.py`)
- Base62 code generation → SQLite database: updates counter (evidence: `database.py`)
- URL record operations → SQLite database: reads and writes (evidence: `database.py`)
- Account and API keys → SQLite database: reads and writes (evidence: `database.py`)
- Click tracking → SQLite database: updates clicks (evidence: `database.py`)
- Top-link query → SQLite database: queries links (evidence: `database.py`)
