https://github.com/mrkazzila/shortener_url_api
!!!ON HOLD!!! Tiny url api using FastApi.
https://github.com/mrkazzila/shortener_url_api
alembic docker docker-compose fastapi poetry postgres pytest sqlachemy
Last synced: about 2 months ago
JSON representation
!!!ON HOLD!!! Tiny url api using FastApi.
- Host: GitHub
- URL: https://github.com/mrkazzila/shortener_url_api
- Owner: mrKazzila
- Created: 2023-08-04T11:48:22.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-01-03T08:33:07.000Z (over 1 year ago)
- Last Synced: 2025-02-01T05:41:33.106Z (over 1 year ago)
- Topics: alembic, docker, docker-compose, fastapi, poetry, postgres, pytest, sqlachemy
- Language: Python
- Homepage:
- Size: 705 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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)
```bash
grpcui -plaintext localhost:50051
````
### Additional docs
* [gRPC docs](docs/grpc/grpc.md)
---
## Architecture Diagrams
DB Schema
Classes Diagram
Packages Diagram
System Diagram
TODO: Add Excalidraw system diagram
---
## Quick Start (Docker & Just)
1. Clone repo
```bash
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
```bash
just infra-up
```
4. Run app (1 1 = partitions & replicas)
```bash
just app-bootstrap 1 1
```
5. Optional monitoring stack
```bash
just mon-up
```
6. See all available commands
```bash
just
````
---
## Local Load Testing (gRPC)
For local load testing, I use **ghz**.
### Example: CreateShortUrl
```bash
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.
---
[](https://github.com/mrKazzila)
[](https://mrkazzila.com)
[](https://www.linkedin.com/in/i-kazakov/)