💡 Não esconde os algoritmos. Rate limiter (token bucket) e cache (TTL/LRU) são implementados do zero para mostrar a engenharia por trás, não escondida atrás de uma lib.

Sobre

LinkForge é um encurtador de URL & API de analytics com pegada de produção, construído com FastAPI. Não é um CRUD de brinquedo — foi desenhado para mostrar a engenharia que separa um endpoint de hobby de um serviço de verdade: autenticação, rate limiting, cache, processamento em background, testes, containerização e CI.

Destaques:

• JWT — registro/login, senhas com PBKDF2-HMAC-SHA256 (salt por usuário, verificação em tempo constante). Nunca texto puro.
• Rate limiting (token bucket) — middleware ASGI próprio, por IP, com Retry-After. Sem precisar de Redis pra uma instância só.
• Cache TTL + LRU — lookups quentes code → URL pulam o banco; thread-safe, limitado, com expiração automática.
• Analytics assíncrono — cliques são registrados em background task, fora do caminho de resposta. Endpoint de stats agrega totais, cliques-por-dia e top referrers.
• Ownership — cada usuário só vê e gerencia seus próprios links.
• Docs OpenAPI automáticas — Swagger UI interativo em /docs, ReDoc em /redoc.
• Totalmente testado — 16 testes pytest cobrindo auth, validação, redirects, analytics e autorização.
• Containerizado + CI — Dockerfile (non-root, healthcheck), docker-compose, GitHub Actions rodando a suíte a cada push.

API

Método	Endpoint	Auth	Descrição
POST	/auth/register	—	Cria uma conta
POST	/auth/login	—	Retorna um token JWT
POST	/links	✅	Cria um link curto (código aleatório ou customizado)
GET	/links	✅	Lista seus links com contagem de cliques
GET	/links/{code}/stats	✅	Analytics de um link
DELETE	/links/{code}	✅	Remove um link
GET	/{code}	—	Redireciona para a URL alvo (302) + registra o clique
GET	/health	—	Liveness probe

Docs completas e interativas em /docs com o app rodando.

Arquitetura

Tecnologias

Camada	Tecnologia
Framework	FastAPI (+ middleware Starlette)
Dados	SQLModel / SQLAlchemy, SQLite (pronto pra Postgres via DATABASE_URL)
Auth	PyJWT + PBKDF2 da stdlib
Testes	pytest + httpx (TestClient)
Ops	Docker, docker-compose, GitHub Actions

Uso

Local:

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

cp .env.example .env   # opcional

uvicorn app.main:app --reload

Abra http://localhost:8000/docs e teste.

Docker:

docker compose up --build

Testes:

pytest -q

A suíte sobe o app contra um SQLite descartável e exercita o ciclo completo (auth → criação → redirect → analytics → autorização).

Licença

MIT.

_{Desenvolvido por Grigori · 2026}