URL Shortener Backend

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                        Clients                          │
└────────────────────────┬────────────────────────────────┘
                         │ HTTP
┌────────────────────────▼────────────────────────────────┐
│              FastAPI (async, uvicorn)                   │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐  │
│  │  Auth API   │  │  URL API     │  │  Analytics    │  │
│  │  /register  │  │  POST /urls  │  │  /summary     │  │
│  │  /login     │  │  GET /urls   │  │               │  │
│  └─────────────┘  └──────────────┘  └───────────────┘  │
│                                                         │
│  ┌─────────────────────────────────────────────────┐    │
│  │         GET /{short_code}  (hot path)           │    │
│  └─────────────────────────────────────────────────┘    │
└────────┬───────────────────────────────────┬────────────┘
         │                                   │
┌────────▼────────┐               ┌──────────▼──────────┐
│  Redis Cluster  │               │   PostgreSQL        │
│                 │               │                     │
│  url:{code}     │◄──cache miss──│  short_urls         │
│  hot:{code}     │               │  click_events       │
│  analytics:queue│               │  analytics_snapshot │
│  ratelimit:*    │               │  users              │
│  qr:{code}      │               │  refresh_tokens     │
└─────────────────┘               └─────────────────────┘
         │
         │  async drain
┌────────▼────────┐
│ Analytics Worker│  (background asyncio Task)
│ batch flush →   │
│ PostgreSQL      │
└─────────────────┘

Redirect Flow (Critical Path)

GET /{short_code}
      │
      ▼
1. Redis GET url:{short_code}
      │
      ├─ HIT → validate expiry → HTTP 302 ──────────────────┐
      │                                                      │
      └─ MISS → PostgreSQL SELECT (active, not expired)      │
                     │                                       │
                     ├─ NOT FOUND → 404                      │
                     │                                       │
                     └─ FOUND → HTTP 302 ────────────────────┤
                                                             │
                              ┌──────────────────────────────┘
                              │  BackgroundTasks (non-blocking)
                              │
                              ├─ cache_warm: Redis SETEX url:{code}
                              ├─ click_track: Redis INCR hot:{code}
                              └─ analytics: Redis RPUSH analytics:queue

Analytics Pipeline

Redirect endpoint
      │
      └── BackgroundTask → Redis RPUSH analytics:queue
                                      │
                      ┌───────────────┘
                      │  Every 5 seconds (configurable)
                      ▼
           AnalyticsProcessor (asyncio.Task)
                      │
                      ├── Redis LRANGE analytics:queue 0 99
                      ├── Redis LTRIM  analytics:queue 100 -1
                      └── PostgreSQL bulk INSERT click_events
                                        + UPDATE short_urls.click_count

Caching Strategy

Rate Limiting

On each request:
  1. ZREMRANGEBYSCORE key -inf (now - window)   # remove stale entries
  2. ZCARD key                                  # current count
  3. If count < limit: ZADD key {now} {uuid}    # admit request
  4. Else: reject 429                           # deny request

Tech Stack

Project Structure

app/
├── api/v1/endpoints/   # Thin route handlers — no business logic
│   ├── auth.py
│   ├── urls.py
│   ├── analytics.py
│   ├── qr.py
│   └── health.py
├── analytics/          # Event value objects + background processor
├── cache/              # Redis client, URL cache, rate limiter, analytics queue
├── core/               # Security, exceptions, structured logging
├── db/                 # SQLAlchemy base + async session factory
├── dependencies/       # FastAPI dependency injection (auth, db, cache)
├── middleware/         # Request logging with request-ID tracing
├── models/             # SQLAlchemy ORM models
├── repositories/       # Data access layer (no business logic)
├── schemas/            # Pydantic v2 request/response models
├── services/           # Business logic layer
├── tasks/              # Background worker lifecycle
├── tests/              # pytest-asyncio test suite
└── utils/              # Short code generation, URL validator, UA parser

Quick Start

With Docker (recommended)

# 1. Clone and configure
cp .env.example .env
# Edit .env — at minimum set SECRET_KEY to a strong random value

# 2. Start all services (Postgres, Redis, API)
docker compose up --build

# 3. Run migrations (first time only — handled by the `migrate` service)
docker compose run --rm migrate

# 4. API is live at http://localhost:8000
# 5. Interactive docs at http://localhost:8000/docs (DEBUG=true only)

Local Development

# Requires Python 3.12, PostgreSQL, Redis

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

cp .env.example .env               # configure DATABASE_URL, REDIS_URL, SECRET_KEY

alembic upgrade head               # apply migrations

uvicorn app.main:app --reload --port 8000

API Reference

Authentication

URLs

Analytics

QR Codes

Redirect

System

Example Requests

# Register
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "MyPass123", "full_name": "John Doe"}'

# Login
TOKEN=$(curl -s -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "MyPass123"}' | jq -r '.access_token')

# Shorten a URL
curl -X POST http://localhost:8000/api/v1/urls \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"original_url": "https://example.com/very/long/path", "custom_alias": "mylink"}'

# Redirect (follow with browser or -L)
curl -L http://localhost:8000/mylink

# Download QR code
curl http://localhost:8000/api/v1/qr/mylink --output mylink.png

# Analytics
curl http://localhost:8000/api/v1/analytics/mylink/summary \
  -H "Authorization: Bearer $TOKEN"

Environment Variables

Running Tests

pip install -r requirements.txt aiosqlite
pytest -v

Security Notes