Local URL Shortener (Python)

A self-contained Python URL shortener with both a CLI and a Flask web interface, designed to demonstrate real-world backend concepts such as hashing, persistence, rate limiting, analytics, and defensive input handling — all in a single, readable file.

Features

• Shorten long URLs into compact, Base62-encoded codes
• Deterministic hashing with secure random fallback for collisions
• Custom short codes with validation
• Local persistence using a JSON datastore
• Duplicate URL detection (same URL → same code)
• Optional link expiration
• Usage tracking and daily click analytics
• Basic rate limiting per user/IP
• Blocked domain filtering and URL normalization
• Command-line interface and Flask web interface
• Single-file implementation for simplicity and portability

---

Tech Stack

• Python 3.9+
• Flask (web interface)
• Standard library only for hashing, persistence, and analytics

Project Structure

shortener.py      # Entire application (CLI + Web)
url_db.json       # Auto-created local datastore

No external database or configuration files are required.

Getting Started

1. Clone the repository

git clone https://github.com/yourusername/local-url-shortener.git
cd local-url-shortener

2. Install dependencies

python -m pip install flask

Running the Application

CLI Mode (default)

python shortener.py

CLI options:

• Shorten a URL
• Expand a short code
• View global statistics

---

Web Mode (Flask)

python shortener.py web

Then open:

http://127.0.0.1:5000

 Web Endpoints

| Endpoint   | Description                           |
| ---------- | ------------------------------------- |
| `/`        | Web UI for shortening URLs            |
| `/shorten` | POST endpoint for creating short URLs |
| `/<code>`  | Redirects to original URL             |

 Analytics & Rate Limiting

* Tracks:

  * Total URLs created
  * Total redirects
  * Per-URL usage count
  * Daily click counts
* Rate limiting:

  * Default: **10 requests per 60 seconds**
  * Enforced per CLI session or web client IP

Security & Validation

* URL normalization to prevent duplicate mismatches
* Domain blocklist support
* Maximum URL length enforcement
* Custom code validation
* Expiration-based link invalidation

 Design Notes

* Uses **hash-based deterministic codes** for consistency
* Falls back to **secure random codes** to avoid collisions
* JSON persistence keeps the project lightweight and portable
* Single-file design emphasizes clarity and maintainability


 Author

**Derek Lenz**
Built as a portfolio project to demonstrate backend engineering fundamentals in Python.