# brick-24/url-shorten architecture

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

## Overview

This is a server-rendered URL-shortening service. A user signs in, submits a URL, receives a short code and admin key, and visitors use the code to redirect to the destination while click data is recorded. Owners can view their links and click counts; authenticated users can also request admin-key-protected analytics. The graph includes the separately implemented Google login and rate limiting. Source excerpts show route-to-service calls, but not deployment wiring, so Cloud Run is omitted.

Main entry points: [`src/routes.py`](https://github.com/brick-24/url-shorten/blob/main/src/routes.py) (HTTP routes), [`src/links.py`](https://github.com/brick-24/url-shorten/blob/main/src/links.py) (Link operations), [`src/database.py`](https://github.com/brick-24/url-shorten/blob/main/src/database.py) (Database sessions), [`src/main.py`](https://github.com/brick-24/url-shorten/blob/main/src/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_routes["HTTP routes<br/>[routes.py]"]
  node_templates["HTML templates"]
  node_static["Static assets"]
end

subgraph group_identity["Identity and access"]
  node_auth["OAuth clients<br/>[auth.py]"]
  node_github["GitHub OAuth"]
  node_google["Google OAuth"]
  node_sessions["Session middleware<br/>[main.py]"]
end

subgraph group_links["Links and analytics"]
  node_link_ops["Link operations<br/>[links.py]"]
  node_models["Link and click models<br/>[models.py]"]
end

subgraph group_runtime["Runtime and storage"]
  node_rate["Rate limiting<br/>[rate_limiting.py]"]
  node_database["Database sessions<br/>[database.py]"]
  node_postgres[("PostgreSQL")]
  node_app["FastAPI application<br/>[main.py]"]
end

node_visitor(("Visitor"))
node_owner(("Link owner"))
node_browser(("Web browser"))
node_destination(("Original destination"))

node_owner -->|"uses"| node_browser
node_visitor -->|"opens links"| node_browser
node_browser -->|"HTTP requests"| node_routes
node_routes -->|"renders"| node_templates
node_browser -->|"loads assets"| node_static
node_routes -->|"uses OAuth clients"| node_auth
node_routes -->|"starts or completes OAuth"| node_github
node_routes -->|"starts or completes OAuth"| node_google
node_routes -->|"reads or updates session"| node_sessions
node_routes -->|"creates, looks up, and queries"| node_link_ops
node_routes -->|"queries URL maps"| node_models
node_link_ops -->|"queries and persists"| node_models
node_routes -->|"gets sessions"| node_database
node_database -->|"opens sessions and initializes tables"| node_postgres
node_link_ops -->|"reads and writes links and clicks"| node_postgres
node_routes -->|"applies limits"| node_rate
node_app -->|"mounts router"| node_routes
node_app -->|"initializes tables"| node_database
node_routes -->|"redirects visitor"| node_destination

click node_routes "https://github.com/brick-24/url-shorten/blob/main/src/routes.py"
click node_templates "https://github.com/brick-24/url-shorten/tree/main/src/templates"
click node_static "https://github.com/brick-24/url-shorten/tree/main/src/static"
click node_auth "https://github.com/brick-24/url-shorten/blob/main/src/auth.py"
click node_sessions "https://github.com/brick-24/url-shorten/blob/main/src/main.py"
click node_rate "https://github.com/brick-24/url-shorten/blob/main/src/rate_limiting.py"
click node_link_ops "https://github.com/brick-24/url-shorten/blob/main/src/links.py"
click node_models "https://github.com/brick-24/url-shorten/blob/main/src/models.py"
click node_database "https://github.com/brick-24/url-shorten/blob/main/src/database.py"
click node_app "https://github.com/brick-24/url-shorten/blob/main/src/main.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_routes,node_templates,node_static,node_browser toneBlue
class node_auth,node_github,node_google,node_sessions toneAmber
class node_link_ops,node_models toneMint
class node_rate,node_database,node_postgres,node_app toneRose
class node_visitor,node_owner,node_destination toneIndigo
```

## Components

### Web interface

- [HTTP routes](https://github.com/brick-24/url-shorten/blob/main/src/routes.py): `src/routes.py`
- [HTML templates](https://github.com/brick-24/url-shorten/tree/main/src/templates): `src/templates`
- [Static assets](https://github.com/brick-24/url-shorten/tree/main/src/static): `src/static`

### Identity and access

- [OAuth clients](https://github.com/brick-24/url-shorten/blob/main/src/auth.py): `src/auth.py`
- **GitHub OAuth**
- **Google OAuth**
- [Session middleware](https://github.com/brick-24/url-shorten/blob/main/src/main.py): `src/main.py`

### Links and analytics

- [Link operations](https://github.com/brick-24/url-shorten/blob/main/src/links.py): `src/links.py`
- [Link and click models](https://github.com/brick-24/url-shorten/blob/main/src/models.py): `src/models.py`

### Runtime and storage

- [Rate limiting](https://github.com/brick-24/url-shorten/blob/main/src/rate_limiting.py): `src/rate_limiting.py`
- [Database sessions](https://github.com/brick-24/url-shorten/blob/main/src/database.py): `src/database.py`
- **PostgreSQL**
- [FastAPI application](https://github.com/brick-24/url-shorten/blob/main/src/main.py): `src/main.py`

### Other components

- **Visitor**
- **Link owner**
- **Web browser**
- **Original destination**

## Connections

- Link owner → Web browser: uses
- Visitor → Web browser: opens links
- Web browser → HTTP routes: HTTP requests
- HTTP routes → HTML templates: renders
- Web browser → Static assets: loads assets
- HTTP routes → OAuth clients: uses OAuth clients
- HTTP routes → GitHub OAuth: starts or completes OAuth
- HTTP routes → Google OAuth: starts or completes OAuth
- HTTP routes → Session middleware: reads or updates session
- HTTP routes → Link operations: creates, looks up, and queries
- HTTP routes → Link and click models: queries URL maps
- Link operations → Link and click models: queries and persists
- HTTP routes → Database sessions: gets sessions
- Database sessions → PostgreSQL: opens sessions and initializes tables
- Link operations → PostgreSQL: reads and writes links and clicks
- HTTP routes → Rate limiting: applies limits
- FastAPI application → HTTP routes: mounts router
- FastAPI application → Database sessions: initializes tables
- HTTP routes → Original destination: redirects visitor