URL Shortener

A fast and simple URL shortener with a dark-themed web UI, custom aliases, and click tracking.

---

Features

• Shorten URLs with a single click
• Custom aliases like /my-link
• Click tracking with last-clicked timestamp
• Dark-themed responsive UI
• REST API for programmatic access
• QR code generation for any link
• Link expiration via ttl_hours
• Async SQLite (aiosqlite)

Quick Start

# Clone the repository
git clone https://github.com/qorexdevs/url-shortener.git
cd url-shortener

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

# Run the server
uvicorn app.main:app --reload

Open http://localhost:8000 in your browser.

Docker

docker compose up -d

The database is stored in a named volume so your data persists across container restarts.

API Documentation

Shorten a URL

POST /api/shorten
Content-Type: application/json

{
  "url": "https://example.com/very/long/url",
  "custom_alias": "my-link"
}

Response:

{
  "original_url": "https://example.com/very/long/url",
  "short_url": "http://localhost:8000/my-link",
  "short_code": "my-link"
}

Get Link Stats

GET /api/stats/{code}

{
  "original_url": "https://example.com/very/long/url",
  "short_url": "http://localhost:8000/my-link",
  "short_code": "my-link",
  "clicks": 42,
  "created_at": "2025-01-01T00:00:00",
  "last_clicked": "2025-01-02T12:30:00"
}

QR Code

GET /api/qr/{code}  ->  PNG image

Returns a QR code image encoding the short URL. Useful for sharing links in print or presentations.

Redirect

GET /{code}  ->  307 redirect to original URL

Configuration

Variable	Default	Description
BASE_URL	http://localhost:8000	Base URL for generated short links
DATABASE_URL	sqlite+aiosqlite:///./shortener.db	Database connection string

Project Structure

url-shortener/
|-- app/
|   |-- __init__.py
|   |-- main.py              # FastAPI application entry point
|   |-- config.py            # Settings and configuration
|   |-- database.py          # Async engine and session
|   |-- models.py            # SQLAlchemy URL model
|   |-- schemas.py           # Pydantic schemas
|   |-- utils.py             # Short code generation
|   |-- routers/
|   |   |-- __init__.py
|   |   |-- api.py           # REST API endpoints
|   |   `-- pages.py         # Web UI routes
|   |-- templates/
|   |   |-- base.html        # Base layout
|   |   |-- index.html       # Main page (shorten form)
|   |   `-- stats.html       # Link statistics page
|   `-- static/
|       |-- css/style.css    # Dark theme styles
|       `-- js/main.js       # Frontend logic
|-- Dockerfile
|-- docker-compose.yml
|-- requirements.txt
|-- .gitignore
`-- README.md

Tech Stack

Component	Technology
Framework	FastAPI 0.115
ORM	SQLAlchemy 2.0 (async)
Database	SQLite via aiosqlite
Templates	Jinja2
Frontend	Vanilla HTML/CSS/JS
Server	Uvicorn

License

MIT

---

_{developed by qorex
GitHub | Telegram}