Production grade URL shortener

Inspiration

Most URL shorteners are built as "Hello World" projects. We wanted to take the opposite approach: How would an SRE build a URL shortener for a high-traffic production environment? We were inspired by the challenge of moving beyond a simple "input-output" script to a resilient system that can handle malicious traffic, provide deep observability, and maintain perfect data integrity.

What it does

This is a production-grade REST API for URL management. It doesn’t just shorten links; it manages their entire lifecycle. Key features include:

• Smart Idempotency: Recognizes duplicate URLs to save database space.
• Auto-Reactivation: Resurrects previously deleted links instead of creating redundant entries.
• Security-First Rate Limiting: Protects the infrastructure from DoS attacks and brute-force attempts.
• Observability Suite: Provides a deep /health check (monitoring DB latency) and structured JSON logging for professional monitoring tools.

How we built it

The project is built on a modern Python 3.13 stack:

• Backend: Flask using the Factory Pattern for modularity and testing.
• Database: PostgreSQL managed via the Peewee ORM for robust relational data handling.
• Testing: A comprehensive integration suite using pytest and pytest-cov, reaching over 90% coverage.
• Ops: Structured logging using a custom JSON formatter and uv for lightning-fast, reproducible environment management.

Challenges we ran into

One major challenge was implementing URL Idempotency with Soft Deletes. Balancing the logic to return an existing link if it’s active—but "reactivating" it if it was previously deleted—required careful state management in the database layer. We also worked through ensuring that our rate-limiting headers and JSON error responses remained consistent across both manual testing and our automated test suite.

Accomplishments that we're proud of

• 85%+ Test Coverage: We didn’t just write code; we proved it works through rigorous integration testing.
• JSON Observability: Implementing a custom logging system that turns standard text logs into machine-readable JSON objects.
• The Runbook: Going beyond code to provide a RUNBOOK.md that guides engineers through 3 AM emergency scenarios.

What we learned

We learned that Reliability is a feature worth having. Building a "simple" app becomes complex when you account for database latency, malformed inputs, and traffic spikes. We gained deep experience in configuring PostgreSQL unique constraints to act as a safety net for race conditions and learned how to use uv to manage a professional Python workspace efficiently.

What's next for Production grade URL shortener

The next steps involve moving from a single-server instance to a distributed system:

• Redis Caching: Adding a cache layer to reduce database hits for the most popular links.
• Global Distribution: Deploying across multiple regions with a global load balancer.
• Analytics Dashboard: Building a frontend to visualize the structured JSON logs in real-time.

Built With

• docker
• flask
• flask-limiter
• github-codespaces
• peewee-orm
• postgresql
• pytest
• pytest-cov
• python-3.13
• restful-api
• structured-json-logging
• uv