A modern, fast, and secure URL shortening system built with FastAPI and enhanced with a 2-tier Machine Learning classification system to detect and block malicious links.
The core philosophy of this project is to provide more than just a redirection service. We aim to protect users from phishing and malware by integrating intelligent classification models at two levels:
- ⚡ Tier 1 (Online): A lightning-fast XGBoost classifier (via ONNX) that performs real-time checks during shortening requests, blocking known threats with <50ms latency.
- 🔍 Tier 2 (Offline): A deep-learning based re-scan of newly added URLs to detect sophisticated threats that might have bypassed the initial check.
- URL Shortening: Generate short codes with collision detection
- User Authentication: JWT-based auth with registration and login
- ML Safety Classification: Two-tier approach (fast + deep inspection)
- Rate Limiting: Redis-backed request throttling
- Background Processing: Celery workers for async classification
- Auto-Remediation: Malicious URLs automatically disabled
- Docker Ready: Full Docker Compose setup for all services
| Category | Technology |
|---|---|
| Framework | FastAPI |
| Database | SQLAlchemy 2.0 (Async) + PostgreSQL |
| Cache & Rate Limiting | Redis |
| Background Tasks | Celery + Redis (broker) |
| Task Monitoring | Flower |
| ML Runtime | ONNX Runtime |
| Dependency Management | uv |
| Linting & Formatting | ruff |
| Testing | pytest + pytest-asyncio |
| CI/CD | GitHub Actions |
- uv installed.
- Redis server running (for rate limiting).
- Clone the Repo:
git clone https://github.com/your-username/url-shortener.git cd url-shortener - Install Dependencies:
uv sync
- Environment Setup:
cp .env.example .env # Edit .env with your configuration - Run Development Server:
uv run fastapi dev app/api.py
Run all services (API, PostgreSQL, Redis, Celery worker, Celery beat, Flower) with:
docker compose upServices available:
- API: http://localhost:8000
- Flower (task monitoring): http://localhost:5555
- Architecture - System design, component layout, and data flow
- Roadmap - Development phases and upcoming features
- API Docs - Interactive Swagger UI (when running)
We welcome contributions! Please see our Contributing Guidelines to get started and check the Roadmap for open tasks.
This project is licensed under the MIT License - see the LICENSE file for details.