DevStage API

API backend para gerenciamento de inscricoes e ranking por indicacoes em um evento ("NLW Connect").

A aplicacao permite:

• cadastrar participantes;
• registrar quem indicou cada novo inscrito;
• contar acessos em links de convite;
• calcular ranking de indicacoes;
• consultar posicao individual no ranking.

O que e este projeto

Este projeto implementa um sistema de referrals (indicacoes) para campanhas/eventos.

Fluxo principal:

1. Um participante se inscreve e recebe/usa um identificador.
2. Outro usuario acessa o link de convite desse participante.
3. O sistema registra o clique no convite.
4. Quando um novo cadastro acontece com referrer, o score do indicador e incrementado.
5. O ranking geral e as metricas individuais podem ser consultados por endpoints.

Stack utilizada

Runtime e linguagem

• Node.js
• TypeScript

Framework HTTP

• Fastify
• @fastify/cors

Validacao e tipagem de contratos

• Zod
• fastify-type-provider-zod

Documentacao da API

• @fastify/swagger
• @fastify/swagger-ui
• Swagger UI em /docs

Persistencia e dados

• PostgreSQL
• Drizzle ORM
• drizzle-kit (migracoes)
• postgres (driver)

Cache e ranking

• Redis
• ioredis

Build e desenvolvimento

• tsx (dev/watch)
• tsup (build)
• Biome (format/lint)

Infra local

• Docker Compose (PostgreSQL e Redis)

Funcionalidades

1) Inscricao no evento

• Endpoint: POST /subscriptions
• Entrada: nome, email, referrer (opcional)
• Regra:
  • se email ja existir, retorna o subscriberId existente;
  • se novo cadastro com referrer, incrementa ranking no Redis.

2) Acesso ao link de convite

• Endpoint: GET /invites/:subscriberId
• Regra:
  • incrementa contador de acessos do convite no Redis;
  • redireciona (302) para WEB_URL com query param referrer.

3) Metricas de ranking por participante

• GET /subscribers/:subscriberId/ranking/clicks
  • quantidade de cliques no link de convite.
• GET /subscribers/:subscriberId/ranking/count
  • score de indicacoes no ranking.
• GET /subscribers/:subscriberId/ranking/position
  • posicao no ranking (1-based), ou null se nao rankeado.

4) Ranking geral

• Endpoint: GET /ranking
• Retorno: top 3 participantes com id, nome e score.

Variaveis de ambiente

O projeto valida variaveis com Zod.

Crie um arquivo .env na raiz com:

PORT=3333 POSTGRES_URL=postgresql://docker:docker@localhost:5432/connect REDIS_URL=redis://localhost:6379 WEB_URL=http://localhost:3000

Como rodar localmente

1) Subir banco e redis

Use Docker Compose:

• PostgreSQL na porta 5432
• Redis na porta 6379

Comando:

docker compose up -d

2) Instalar dependencias

npm install

3) Rodar migracoes

Como o projeto usa Drizzle, execute:

npx drizzle-kit migrate

4) Rodar em modo desenvolvimento

npm run dev

Servidor padrao em http://localhost:3333 Documentacao em http://localhost:3333/docs

Build

npm run build

Endpoints (resumo)

• POST /subscriptions
• GET /invites/:subscriberId
• GET /subscribers/:subscriberId/ranking/clicks
• GET /subscribers/:subscriberId/ranking/count
• GET /subscribers/:subscriberId/ranking/position
• GET /ranking

Estrutura principal

src/

• server.ts -> bootstrap da API e registro de rotas/plugins
• env.ts -> validacao de variaveis de ambiente
• routes/ -> definicao de contratos HTTP
• functions/ -> regras de negocio
• drizzle/ -> cliente ORM, schema e migracoes
• redis/ -> cliente Redis

Observacoes tecnicas

• O score de ranking e armazenado em sorted set no Redis (referral:ranking).
• O contador de acessos de convite e armazenado em hash no Redis (referral:access-count).
• A tabela subscriptions garante unicidade por email.