URL Shortener gRPC API

---

Features

• High-performance async gRPC API
• URL shortening with PostgreSQL + Redis caching
• Event-driven via Kafka (FastStream)
• Full DDD / Clean Architecture setup
• Async ORM with SQLAlchemy & Alembic migrations
• Unit of Work & transaction management
• DI with Dishka, testing with pytest
• Observability stack: Prometheus, Grafana, Loki, Promtail

---

Tech Stack

Layer	Tools & Tech
API	gRPC (protobuf)
DB & ORM	PostgreSQL, SQLAlchemy (async), Alembic
Caching	Redis
Messaging	Kafka (FastStream)
DI & Architecture	Dishka, DDD, Clean Architecture
Testing & QA	pytest, Ruff, Pyright
Observability	Prometheus, Grafana, Loki, Promtail
DevOps & Containers	Docker, Docker Compose, Justfile

---

Documentation

gRPC UI (grpcui)

grpcui -plaintext localhost:50051

Additional docs

• gRPC docs

---

Architecture Diagrams

DB Schema

Classes Diagram

Packages Diagram

System Diagram

TODO: Add Excalidraw system diagram

---

Quick Start (Docker & Just)

1. Clone repo

  git clone git@github.com:mrKazzila/shortener_url_api.git
  cd shortener_url_api/backend

2. Configure env & pgbouncer (edit env.env and backend/docker/compose/infra/pgbouncer/userlist.txt)

3. Start infrastructure

  just infra-up

4. Run app (1 1 = partitions & replicas)

  just app-bootstrap 1 1

5. Optional monitoring stack

  just mon-up

6. See all available commands

  just

---

Local Load Testing (gRPC)

For local load testing, I use ghz.

Example: CreateShortUrl

ghz --insecure \
  --proto ./proto/shortener_app/v1/shortener_app.proto \
  --call shortener_app.v1.ShortenerService.CreateShortUrl \
  -d '{"target_url":"https://example.com"}' \
  -c 50 \
  --duration 10m \
  --import-paths ./proto \
  localhost:50051

Example results:

• ~800k requests in 10 minutes
• ~1330 RPS
• Avg latency ~37ms
• P99 ~91ms
• Occasional Unavailable errors on the local network during aggressive competition

---

⚠️ Over-engineering Note

Why so many technologies?

This project intentionally uses advanced technologies (Kafka, Redis, DI, DDD, async ORM) for a simple URL shortener to showcase scalable, maintainable microservice design.

---