🚀 DevStage – API

📌 Descrição

O backend do DevStage é uma API REST desenvolvida para gerenciar inscrições em eventos técnicos e sistemas de indicação (referral) em tempo real.

A aplicação foi projetada com foco em alta performance, permitindo que cada inscrito possua um identificador único para convidar outros participantes e subir em um ranking global baseado em engajamento.

O sistema processa:

• 📥 Inscrições de participantes
• 🔗 Geração e acesso a links de convite
• 📊 Métricas de cliques
• 🏆 Ranking global de indicações

🏗 Visão Arquitetural

A arquitetura foi construída sobre Node.js utilizando o framework Fastify, escolhido por sua alta performance e baixo overhead.

O sistema utiliza dois bancos de dados com responsabilidades distintas:

• 🐘 PostgreSQL → Persistência de dados estruturados (inscrições)
• ⚡ Redis → Métricas e ranking em memória (alta velocidade)

Validações são realizadas com Zod, garantindo consistência de tipos entre requisição e lógica interna.

A documentação da API é gerada automaticamente via Swagger (OpenAPI).

🧩 Diagrama Simplificado

[Cliente/Frontend]
        │
        ▼
[API: Node.js + Fastify]
        │
        ├── 🐘 PostgreSQL (Inscrições)
        └── ⚡ Redis (Métricas e Ranking)
        
        📘 Swagger disponível em /docs

🛠 Decisões Técnicas

🟢 Node.js + TypeScript (v22 LTS)

• Segurança de tipos
• Melhor manutenção e escalabilidade
• Execução com TSX em ambiente de desenvolvimento

⚡ Fastify

• Framework de alto desempenho
• Serialização eficiente
• Integração natural com validação

🧪 Zod + Fastify Type Provider Zod

• Validação de body, params e query
• Inferência automática de tipos
• Redução de inconsistências entre schema e código

🐘 PostgreSQL

• Persistência relacional
• Integridade transacional
• Armazena dados de inscritos

⚡ Redis

• Sorted Sets (ZSET) → Ranking por pontuação
• Hashes → Contagem de cliques por usuário
• Alta performance para operações frequentes de leitura

🧱 Drizzle ORM

• ORM tipado
• Migrations organizadas
• Integração direta com TypeScript

📘 Swagger (OpenAPI)

• Documentação automática
• Interface interativa em /docs
• Base para geração de cliente HTTP no frontend (Orval)

🧹 Biome

• Lint + Formatter de alta performance
• Padronização do código

🌐 Principais Endpoints

🐳 Como Rodar (Docker + API)

1️⃣ Subir infraestrutura

Na raiz do projeto:

docker compose up -d

Isso iniciará:

• 🐘 PostgreSQL (porta 5432)
• ⚡ Redis (porta 6379)

2️⃣ Instalar dependências

npm install

3️⃣ Rodar aplicação

npm run dev

Servidor disponível em:

http://localhost:3333

Swagger disponível em:

http://localhost:3333/docs

🔐 Variáveis de Ambiente

Arquivo .env:

# Server
PORT=3333

# Database
DATABASE_URL=postgresql://docker:docker@localhost:5432/connect

# Redis
REDIS_URL=redis://localhost:6379

# URLs
API_URL=<http://localhost:3333>
WEB_URL=<http://localhost:3000>

No ambiente Docker, as variáveis podem ser configuradas diretamente no docker-compose.yml.

📂 Estrutura de Pastas

src/
 ├── routes/        → Definição de endpoints e schemas de validação
 ├── functions/     → Casos de uso e lógica de negócio
 ├── drizzle/       → ORM, schemas das tabelas e migrations
 ├── http/          → Configuração do servidor Fastify e plugins (Swagger, CORS, Zod)
 ├── env.ts         → Validação de variáveis com Zod
 └── server.ts      → Inicialização da aplicação

🗺 Roadmap Técnico Realista

🔹 Curto Prazo

• Implementar testes automatizados (Vitest ou Jest)
• Melhorar tratamento centralizado de erros
• Adicionar logs estruturados

🔹 Médio Prazo

• Implementar cache estratégico no Redis
• Adicionar rate limiting
• Criar healthcheck endpoint

🔹 Longo Prazo

• Containerização completa da API
• Deploy em ambiente cloud (Railway, Fly.io ou AWS)
• Integração com agentes de IA para consultas analíticas