deadletter

Inspiration

I wanted to try something new, so I built deadletter, a production-focused URL shortener with an immutable event audit log. Instead of only building CRUD, I focused on reliability, incident response, and operational clarity.

What it does

Deadletter shortens URLs, redirects active links, and soft-deletes inactive ones.It also records every URL mutation (created, updated, deleted) in an append-only event log, with consistent JSON errors and health/metrics endpoints for operations.

How we built it

We used Flask + Peewee + PostgreSQL for the API and data layer, and Typer/Rich for a CLI-first workflow.Each URL mutation and event write happens in one DB transaction to keep state and audit history in sync.The stack is containerized with Docker Compose, with optional Prometheus/Grafana observability.

Challenges we ran into

• Keeping URL writes and audit events fully atomic.

• Getting soft-delete behavior right (inactive redirects return JSON 404).

• Enforcing one consistent JSON error shape across all failure paths.

• Balancing hackathon speed with production-quality docs and operations.

Accomplishments that we're proud of

• Reliable transactional audit logging for all mutations.

• Clean, predictable API behavior for edge cases and failures.

• Solid ops foundation: health checks, metrics, runbook, failure modes, and capacity planning.

• CI-driven workflow that prioritizes test-first reliability.

What we learned

• Reliability is mostly about predictable failure handling.

• Documentation is part of production readiness, not an afterthought.

• Consistent contracts make systems easier to debug and operate.

• Simple architectures can still be production-grade with disciplined engineering.

What's next for deadletter

• Run behind Gunicorn for stronger production serving.

• Add DB pooling and Redis caching for higher redirect throughput.

• Move to managed Postgres and horizontal API scaling.

• Expand alerting and SLO/error-budget tracking for ongoing reliability.

Built With

• digitalocean
• docker
• docker-compose
• flask
• github-actions
• grafana
• peewee
• postgresql
• prometheus
• pytest
• python
• rich
• typer
• uv