ADR-001 — NestJS como Framework Backend

Data: 2026-03
Status: Ativo

Contexto

Precisávamos de um framework backend para a API REST do CRM. As necessidades eram:

• TypeScript nativo
• Suporte a injeção de dependência (muitos serviços inter-relacionados)
• Suporte a módulos (WhatsApp, Campanhas, ERP, etc.)
• Suporte nativo a filas (BullMQ) e jobs agendados
• Ecossistema maduro com guards, interceptors, pipes

Alternativas consideradas

Alternativa	Por que descartada
Express puro	Sem estrutura opinada — cresceria como spaghetti
Fastify	Bom, mas menos ecossistema para módulos e RBAC
Hono	Leve demais para as necessidades de enterprise do sistema
tRPC	Acoplaria o frontend ao backend — queremos API pública

Decisão

NestJS — framework opinado, baseado em decorators, com suporte nativo a:

• @Module(), @Injectable() para DI
• @Guard(), @Interceptor(), @Pipe() para middleware
• @UseGuards(), @Permissions() para RBAC
• @Cron() para jobs agendados
• BullMQ via @nestjs/bullmq

Consequências

Positivas:

• Estrutura de código consistente entre módulos
• Guards encadeados são declarativos e fáceis de auditar
• AsyncLocalStorage via TenantInterceptor funciona bem com o modelo de DI
• BullMQ integrado nativamente

Negativas:

• Maior complexidade inicial para devs não familiarizados com Angular-style DI
• Decorators são mais difíceis de testar em isolamento
• Startup mais lento que Express puro

Referências de implementação

• Guards: backend/src/common/guards/
• Módulos: backend/src/modules/
• Configuração: backend/src/app.module.ts