# pathangufran/url-shortener architecture

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

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

## Overview

This is a Django REST backend for shortening URLs. The main workflow is an authenticated user creating and managing a short URL, then a visitor resolving its code: the redirect handler asks the URL service to check Redis and fall back to PostgreSQL, redirects to the destination, and initiates click analytics. Separate account and analytics APIs support authentication, reporting, and event retrieval; analytics can record click details asynchronously. The README documents PostgreSQL, Redis, and API capabilities; some routes and integrations are not shown in sampled source, so those links are documented or left unverified.

Main entry points: [`apps/shortener/views.py`](https://github.com/pathangufran/url-shortener/blob/main/apps/shortener/views.py) (URL APIs), [`apps/shortener/services.py`](https://github.com/pathangufran/url-shortener/blob/main/apps/shortener/services.py) (URL service), [`apps/analytics/services.py`](https://github.com/pathangufran/url-shortener/blob/main/apps/analytics/services.py) (Analytics service), [`apps/accounts/views.py`](https://github.com/pathangufran/url-shortener/blob/main/apps/accounts/views.py) (Account APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API layer"]
  node_accounts_api["Account APIs<br/>[views.py]"]
  node_auth_service["Authentication<br/>[services.py]"]
  node_account_data["Account serializers<br/>[serializers.py]"]
end

subgraph group_urls["URL management"]
  node_url_api["URL APIs<br/>[views.py]"]
  node_url_service["URL service<br/>[services.py]"]
  node_url_data["URL serializers<br/>[serializers.py]"]
  node_url_model[("Short URL records<br/>[models.py]")]
  node_qr["QR generation<br/>[qr.py]"]
  node_url_task["URL background task<br/>[tasks.py]"]
end

subgraph group_analytics["Click analytics"]
  node_analytics_api["Analytics APIs<br/>[views.py]"]
  node_analytics_service["Analytics service<br/>[services.py]"]
  node_analytics_data["Analytics serializers<br/>[serializers.py]"]
  node_click_model[("Click event records<br/>[models.py]")]
  node_click_task["Click event worker<br/>[tasks.py]"]
end

subgraph group_platform["Shared services"]
  node_throttle["Request throttling<br/>[throttling.py]"]
  node_rate_limiter["Rate limiter<br/>[rate_limiter.py]"]
  node_redis_cache["URL cache<br/>[redis_client.py]"]
  node_settings["Runtime settings<br/>[base.py]"]
  node_errors["API error handling<br/>[exceptions.py]"]
end

node_client(("Client"))
node_redis[("Redis")]
node_postgres[("PostgreSQL")]
node_celery["Celery worker"]

node_client -->|"authenticates"| node_accounts_api
node_accounts_api -->|"delegates to"| node_auth_service
node_accounts_api -->|"serializes with"| node_account_data
node_client -->|"manages URLs"| node_url_api
node_url_api -->|"delegates to"| node_url_service
node_url_api -->|"serializes with"| node_url_data
node_url_service -->|"reads and writes"| node_url_model
node_url_api -->|"generates QR"| node_qr
node_client -->|"resolves code"| node_url_api
node_url_api -->|"resolves code"| node_url_service
node_url_service -->|"checks and fills"| node_redis_cache
node_redis_cache -->|"reads and writes"| node_redis
node_url_api -->|"records click"| node_analytics_service
node_url_service -->|"loads URL"| node_postgres
node_client -->|"requests reports"| node_analytics_api
node_analytics_api -->|"queries"| node_analytics_service
node_analytics_api -->|"serializes with"| node_analytics_data
node_analytics_service -->|"checks ownership"| node_url_model
node_analytics_service -->|"queries events"| node_click_model
node_analytics_service -->|"queues event"| node_click_task
node_click_task -->|"persists event"| node_click_model
node_throttle -->|"checks quota"| node_rate_limiter
node_accounts_api -->|"applies throttles"| node_throttle
node_url_api -->|"applies throttles"| node_throttle
node_analytics_api -->|"applies throttles"| node_throttle
node_settings -.->|"configures cache"| node_redis
node_settings -.->|"configures database"| node_postgres
node_click_task -.->|"runs asynchronously"| node_celery
node_url_task -.->|"runs asynchronously"| node_celery
node_settings -->|"sets handler"| node_errors

click node_accounts_api "https://github.com/pathangufran/url-shortener/blob/main/apps/accounts/views.py"
click node_auth_service "https://github.com/pathangufran/url-shortener/blob/main/apps/accounts/services.py"
click node_account_data "https://github.com/pathangufran/url-shortener/blob/main/apps/accounts/serializers.py"
click node_url_api "https://github.com/pathangufran/url-shortener/blob/main/apps/shortener/views.py"
click node_url_service "https://github.com/pathangufran/url-shortener/blob/main/apps/shortener/services.py"
click node_url_data "https://github.com/pathangufran/url-shortener/blob/main/apps/shortener/serializers.py"
click node_url_model "https://github.com/pathangufran/url-shortener/blob/main/apps/shortener/models.py"
click node_qr "https://github.com/pathangufran/url-shortener/blob/main/apps/shortener/utils/qr.py"
click node_url_task "https://github.com/pathangufran/url-shortener/blob/main/apps/shortener/tasks.py"
click node_analytics_api "https://github.com/pathangufran/url-shortener/blob/main/apps/analytics/views.py"
click node_analytics_service "https://github.com/pathangufran/url-shortener/blob/main/apps/analytics/services.py"
click node_analytics_data "https://github.com/pathangufran/url-shortener/blob/main/apps/analytics/serializers.py"
click node_click_model "https://github.com/pathangufran/url-shortener/blob/main/apps/analytics/models.py"
click node_click_task "https://github.com/pathangufran/url-shortener/blob/main/apps/analytics/tasks.py"
click node_throttle "https://github.com/pathangufran/url-shortener/blob/main/apps/shortener/utils/throttling.py"
click node_rate_limiter "https://github.com/pathangufran/url-shortener/blob/main/apps/shortener/utils/rate_limiter.py"
click node_redis_cache "https://github.com/pathangufran/url-shortener/blob/main/apps/shortener/utils/redis_client.py"
click node_settings "https://github.com/pathangufran/url-shortener/blob/main/config/settings/base.py"
click node_errors "https://github.com/pathangufran/url-shortener/blob/main/config/exceptions.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_accounts_api,node_auth_service,node_account_data,node_client toneBlue
class node_url_api,node_url_service,node_url_data,node_url_model,node_qr,node_url_task,node_redis,node_postgres toneAmber
class node_analytics_api,node_analytics_service,node_analytics_data,node_click_model,node_click_task toneMint
class node_throttle,node_rate_limiter,node_redis_cache,node_settings,node_errors,node_celery toneRose
```

## Components

### API layer

- [Account APIs](https://github.com/pathangufran/url-shortener/blob/main/apps/accounts/views.py): `apps/accounts/views.py`
- [Authentication](https://github.com/pathangufran/url-shortener/blob/main/apps/accounts/services.py): `apps/accounts/services.py`
- [Account serializers](https://github.com/pathangufran/url-shortener/blob/main/apps/accounts/serializers.py): `apps/accounts/serializers.py`

### URL management

- [URL APIs](https://github.com/pathangufran/url-shortener/blob/main/apps/shortener/views.py): `apps/shortener/views.py`
- [URL service](https://github.com/pathangufran/url-shortener/blob/main/apps/shortener/services.py): `apps/shortener/services.py`
- [URL serializers](https://github.com/pathangufran/url-shortener/blob/main/apps/shortener/serializers.py): `apps/shortener/serializers.py`
- [Short URL records](https://github.com/pathangufran/url-shortener/blob/main/apps/shortener/models.py): `apps/shortener/models.py`
- [QR generation](https://github.com/pathangufran/url-shortener/blob/main/apps/shortener/utils/qr.py): `apps/shortener/utils/qr.py`
- [URL background task](https://github.com/pathangufran/url-shortener/blob/main/apps/shortener/tasks.py): `apps/shortener/tasks.py`

### Click analytics

- [Analytics APIs](https://github.com/pathangufran/url-shortener/blob/main/apps/analytics/views.py): `apps/analytics/views.py`
- [Analytics service](https://github.com/pathangufran/url-shortener/blob/main/apps/analytics/services.py): `apps/analytics/services.py`
- [Analytics serializers](https://github.com/pathangufran/url-shortener/blob/main/apps/analytics/serializers.py): `apps/analytics/serializers.py`
- [Click event records](https://github.com/pathangufran/url-shortener/blob/main/apps/analytics/models.py): `apps/analytics/models.py`
- [Click event worker](https://github.com/pathangufran/url-shortener/blob/main/apps/analytics/tasks.py): `apps/analytics/tasks.py`

### Shared services

- [Request throttling](https://github.com/pathangufran/url-shortener/blob/main/apps/shortener/utils/throttling.py): `apps/shortener/utils/throttling.py`
- [Rate limiter](https://github.com/pathangufran/url-shortener/blob/main/apps/shortener/utils/rate_limiter.py): `apps/shortener/utils/rate_limiter.py`
- [URL cache](https://github.com/pathangufran/url-shortener/blob/main/apps/shortener/utils/redis_client.py): `apps/shortener/utils/redis_client.py`
- [Runtime settings](https://github.com/pathangufran/url-shortener/blob/main/config/settings/base.py): `config/settings/base.py`
- [API error handling](https://github.com/pathangufran/url-shortener/blob/main/config/exceptions.py): `config/exceptions.py`

### Other components

- **Client**
- **Redis**
- **PostgreSQL**
- **Celery worker**

## Connections

- Client → Account APIs: authenticates (evidence: `README.md`)
- Account APIs → Authentication: delegates to (evidence: `apps/accounts/views.py`)
- Account APIs → Account serializers: serializes with (evidence: `apps/accounts/views.py`)
- Client → URL APIs: manages URLs (evidence: `README.md`)
- URL APIs → URL service: delegates to (evidence: `apps/shortener/views.py`)
- URL APIs → URL serializers: serializes with (evidence: `apps/shortener/views.py`)
- URL service → Short URL records: reads and writes (evidence: `apps/shortener/services.py`)
- URL APIs → QR generation: generates QR (evidence: `apps/shortener/views.py`)
- Client → URL APIs: resolves code (evidence: `README.md`)
- URL APIs → URL service: resolves code (evidence: `apps/shortener/views.py`)
- URL service → URL cache: checks and fills (evidence: `apps/shortener/services.py`)
- URL cache → Redis: reads and writes (evidence: `apps/shortener/utils/redis_client.py`)
- URL APIs → Analytics service: records click (evidence: `apps/shortener/views.py`)
- URL service → PostgreSQL: loads URL (evidence: `apps/shortener/services.py`)
- Client → Analytics APIs: requests reports (evidence: `README.md`)
- Analytics APIs → Analytics service: queries (evidence: `apps/analytics/views.py`)
- Analytics APIs → Analytics serializers: serializes with (evidence: `apps/analytics/views.py`)
- Analytics service → Short URL records: checks ownership (evidence: `apps/analytics/services.py`)
- Analytics service → Click event records: queries events (evidence: `apps/analytics/services.py`)
- Analytics service → Click event worker: queues event (evidence: `apps/analytics/services.py`)
- Click event worker → Click event records: persists event (evidence: `apps/analytics/tasks.py`)
- Request throttling → Rate limiter: checks quota (evidence: `apps/shortener/utils/throttling.py`)
- Account APIs → Request throttling: applies throttles (evidence: `apps/accounts/views.py`)
- URL APIs → Request throttling: applies throttles (evidence: `apps/shortener/views.py`)
- Analytics APIs → Request throttling: applies throttles (evidence: `apps/analytics/views.py`)
- Runtime settings → Redis: configures cache (evidence: `README.md`)
- Runtime settings → PostgreSQL: configures database (evidence: `README.md`)
- Click event worker → Celery worker: runs asynchronously (evidence: `README.md`)
- URL background task → Celery worker: runs asynchronously (evidence: `README.md`)
- Runtime settings → API error handling: sets handler (evidence: `config/settings/base.py`)
