Skip to main content
pré-requisitos:
  • Node.js versão 19 ou superior
  • Wrangler CLI instalado
  • Acesso ao Cloudflare Workers
  • Repository com wrangler.toml configurado
este guia te ajuda a configurar o ambiente de desenvolvimento para trabalhar com nossa API do dashboard backend.
1

configure o ambiente backend

# clone o repositório
git clone [REPO_URL]
cd dashboard-backend

# instale dependências
npm install
2

configure as variáveis de ambiente

você precisará configurar as seguintes variáveis no wrangler.toml:
[vars]
JWT_SECRET = "seu_jwt_secret"
BEEHIIV_API_KEY = "sua_api_key"
GEMINI_API_KEY = "sua_gemini_key"
RESEND_API_KEY = "sua_resend_key"
# ... outras variáveis
nunca commite secrets reais no repositório. use wrangler secret put para secrets sensíveis.
3

execute o servidor de desenvolvimento

# inicia o servidor local conectado ao ambiente remoto
npm run dev
sua API estará disponível em http://localhost:8787.
4

teste os endpoints

você pode testar os endpoints usando curl ou Postman:
# teste um endpoint público
curl http://localhost:8787/referrals/count

# teste um endpoint autenticado
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     http://localhost:8787/referrals

​
estrutura do projeto

nossa API é organizada da seguinte forma: 
dashboard-backend/
├── src/
│   ├── routes/          # definições de rotas
│   ├── handlers/        # lógica de negócio
│   ├── services/        # integrações externas
│   ├── middleware/      # autenticação e cache
│   ├── schema/          # schemas do banco
│   └── types/           # tipos TypeScript
├── drizzle/             # migrações do banco
└── wrangler.toml        # configuração do Workers

​
bancos de dados

ossa arquitetura utiliza múltiplos bancos D1 especializados:

📊 DB

dados principais, métricas e newsletters

🎯 STREAKS

gamificação, leituras e engagement

👥 CRM

gestão de relacionamento com clientes

📝 FORMS

formulários dinâmicos e submissions

​
migrações do banco

para aplicar migrações localmente: 
# gerar nova migração
npm run generate

# aplicar migrações localmente
npm run migrate

​
deploy para produção

quando estiver pronto para fazer deploy: 
# deploy com minificação e source maps
npm run deploy
o deploy inclui automaticamente integração com Sentry para monitoramento de erros.

​
ferramentas recomendadas

para melhor experiência de desenvolvimento:
  • VSCode com extensões TypeScript
  • Drizzle Kit para gestão do banco
  • Postman ou Insomnia para teste de APIs
  • Wrangler para gestão do Cloudflare Workers

​
solução de problemas

instale o wrangler CLI globalmente:
npm install -g wrangler
ou use via npx:
npx wrangler dev --remote
faça login no Cloudflare:
wrangler login
verifique se o account_id está correto no wrangler.toml.
verifique se os database IDs estão corretos no wrangler.toml e se os bancos existem no painel do Cloudflare.
verifique os logs do Sentry ou use wrangler tail para debug em tempo real:
wrangler tail
dica: use console.log() liberalmente durante desenvolvimento - os logs aparecerão no terminal com npm run dev.