# ahmetfbalci/url-shortener-api architecture

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

- Interactive diagram: https://gitdiagram.com/ahmetfbalci/url-shortener-api
- Repository: https://github.com/ahmetfbalci/url-shortener-api

## Overview

This is a FastAPI URL-shortening API: clients submit a URL, the service generates and stores a short code, and later requests resolve that code to a redirect. Its documented capabilities include Redis caching, expiration, click tracking, and health checks. The graph separates API, application logic, persistence, and configuration. Source excerpts show the main request paths; the README supplies some capability details. Note: the redirect service returns immediately on a cache hit, before incrementing the click count, so the documented count behavior is not true for cached redirects.

Main entry points: [`app/services/url_service.py`](https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/services/url_service.py) (Redirect Resolution), [`app/db/database.py`](https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/db/database.py) (DB Session), [`app/main.py`](https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/main.py) (FastAPI App), [`app/api/routes/urls.py`](https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/api/routes/urls.py) (URL Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API"]
  node_app["FastAPI App<br/>[main.py]"]
  node_routes["URL Routes<br/>[urls.py]"]
  node_input["URL Schemas<br/>[url.py]"]
end

subgraph group_logic["URL Logic"]
  node_create["Short URL Creation<br/>[url_service.py]"]
  node_redirect["Redirect Resolution<br/>[url_service.py]"]
  node_expiry["Link Expiration<br/>[url_service.py]"]
  node_clicks["Click Tracking<br/>[url_service.py]"]
end

subgraph group_storage["Persistence"]
  node_cache[("Redis Cache<br/>[redis.py]")]
  node_model["URL ORM Model<br/>[url_models.py]"]
  node_session["DB Session<br/>[database.py]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_runtime["Runtime Configuration"]
  node_settings["Settings<br/>[config.py]"]
end

node_client(("API Client"))
node_browser(("Redirect Recipient"))

node_client -->|"sends requests"| node_app
node_app -->|"registers routes"| node_routes
node_routes -->|"validates input"| node_input
node_routes -->|"calls creation"| node_create
node_routes -->|"calls resolution"| node_redirect
node_create -->|"queries and creates"| node_model
node_create -->|"uses session"| node_session
node_redirect -->|"reads and populates"| node_cache
node_redirect -->|"looks up URL"| node_model
node_redirect -->|"checks expiration"| node_expiry
node_redirect -->|"increments count"| node_clicks
node_redirect -->|"returns redirect"| node_browser
node_model -->|"uses base"| node_session
node_session -->|"connects to"| node_postgres
node_app -->|"pings health"| node_cache
node_app -->|"checks health"| node_session
node_session -->|"loads connection config"| node_settings
node_cache -->|"loads connection config"| node_settings

click node_app "https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/main.py"
click node_routes "https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/api/routes/urls.py"
click node_input "https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/schemes/url.py"
click node_create "https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/services/url_service.py"
click node_redirect "https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/services/url_service.py"
click node_expiry "https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/services/url_service.py"
click node_clicks "https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/services/url_service.py"
click node_cache "https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/db/redis.py"
click node_model "https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/models/url_models.py"
click node_session "https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/db/database.py"
click node_settings "https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/core/config.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_app,node_routes,node_input,node_client toneBlue
class node_create,node_redirect,node_expiry,node_clicks toneAmber
class node_cache,node_model,node_session,node_postgres toneMint
class node_settings toneRose
class node_browser toneIndigo
```

## Components

### API

- [FastAPI App](https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/main.py): `app/main.py`
- [URL Routes](https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/api/routes/urls.py): `app/api/routes/urls.py`
- [URL Schemas](https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/schemes/url.py): `app/schemes/url.py`

### URL Logic

- [Short URL Creation](https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/services/url_service.py): `app/services/url_service.py`
- [Redirect Resolution](https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/services/url_service.py): `app/services/url_service.py`
- [Link Expiration](https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/services/url_service.py): `app/services/url_service.py`
- [Click Tracking](https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/services/url_service.py): `app/services/url_service.py`

### Persistence

- [Redis Cache](https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/db/redis.py): `app/db/redis.py`
- [URL ORM Model](https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/models/url_models.py): `app/models/url_models.py`
- [DB Session](https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/db/database.py): `app/db/database.py`
- **PostgreSQL**

### Runtime Configuration

- [Settings](https://github.com/ahmetfbalci/url-shortener-api/blob/main/app/core/config.py): `app/core/config.py`

### Other components

- **API Client**
- **Redirect Recipient**

## Connections

- API Client → FastAPI App: sends requests (evidence: `README.md`)
- FastAPI App → URL Routes: registers routes (evidence: `app/main.py`)
- URL Routes → URL Schemas: validates input (evidence: `app/api/routes/urls.py`)
- URL Routes → Short URL Creation: calls creation (evidence: `app/api/routes/urls.py`)
- URL Routes → Redirect Resolution: calls resolution (evidence: `app/api/routes/urls.py`)
- Short URL Creation → URL ORM Model: queries and creates (evidence: `app/services/url_service.py`)
- Short URL Creation → DB Session: uses session (evidence: `app/api/routes/urls.py`)
- Redirect Resolution → Redis Cache: reads and populates (evidence: `app/services/url_service.py`)
- Redirect Resolution → URL ORM Model: looks up URL (evidence: `app/services/url_service.py`)
- Redirect Resolution → Link Expiration: checks expiration (evidence: `app/services/url_service.py`)
- Redirect Resolution → Click Tracking: increments count (evidence: `app/services/url_service.py`)
- Redirect Resolution → Redirect Recipient: returns redirect (evidence: `app/services/url_service.py`)
- URL ORM Model → DB Session: uses base (evidence: `app/models/url_models.py`)
- DB Session → PostgreSQL: connects to (evidence: `app/db/database.py`)
- FastAPI App → Redis Cache: pings health (evidence: `app/main.py`)
- FastAPI App → DB Session: checks health (evidence: `app/main.py`)
- DB Session → Settings: loads connection config (evidence: `app/db/database.py`)
- Redis Cache → Settings: loads connection config (evidence: `app/db/redis.py`)
