Arquitetura Backend

Padrões arquiteturais, convenções e fluxos dos backends NestJS da equipe (Clean Architecture)

Referência oficial para o time de desenvolvimento. Este guia descreve padrões arquiteturais, convenções e fluxos — não um catálogo de bibliotecas ou endpoints.

O modelo descrito aqui segue o Geiko Service (backend CRM da plataforma Qyon), construído com NestJS e Clean Architecture adaptada ao ecossistema Nest.

Objetivo da arquitetura

Isolar regras de negócio de frameworks, banco de dados e integrações externas.
Permitir troca de implementações (ex.: outro ORM ou broker) sem alterar use cases.
Manter contratos explícitos entre camadas via Gateways.
Suportar multi-tenant (um banco MSSQL por empresa) de forma consistente.

Regra de dependência

As dependências apontam sempre para dentro:

infra  →  app  →  domain
external  →  app (parcialmente, ver [Exceções pragmáticas](/docs/arquitetura/excecoes-pragmaticas))

Camada	Pasta	Pode importar	Não deve importar
Domain	`src/domain/`	Apenas tipos/utilitários puros	`app/`, `infra/`, Nest concreto
Application	`src/app/`	`domain/`, gateways (abstratos)	`Knex*Repository`, `AWSS3Service`, etc.
Infrastructure	`src/infra/`	`app/`, `domain/`	—
External	`src/external/`	`infra/configuration` (EnvConfig)	Use cases

Use cases nunca importam implementações concretas de persistência. Eles dependem exclusivamente de classes abstratas em src/app/gateways/.

Diagrama de camadas

Mapa de pastas (`src/`)

Pasta	Responsabilidade
`src/domain/dtos/`	Contratos de entrada/saída da API; validação com `class-validator`
`src/domain/enums/`	Constantes compartilhadas (permissões, ordenação, flags)
`src/domain/decorators/`	Validadores/transformadores customizados para DTOs
`src/domain/mappers/`	Mappers raros entity → response DTO (maioria usa `getFriendlyObject()`)
`src/app/entities/`	Objetos de domínio com comportamento (getters, regras)
`src/app/gateways/`	Contratos abstratos (ports) — persistência e infra transversal
`src/app/use-cases/`	Orquestração de negócio; um `execute()` por classe
`src/infra/database/knex/`	Knex providers, mappers, repositories
`src/infra/http/`	API principal (JWT), controllers, middlewares
`src/infra/http-public/`	API pública (`x-company-key`)
`src/infra/http-internal/`	API interna (`internal-key`)
`src/infra/broker/`	RabbitMQ (publish/subscribe)
`src/infra/s3/`	Upload e URLs assinadas AWS
`src/infra/email/`	Envio de e-mail e consumers
`src/infra/reports/`	Consumers de relatórios assíncronos
`src/infra/gci/`	Guards e decorators de permissão/contexto
`src/infra/encrypt/`	JWT e hashing
`src/external/`	Clientes HTTP para microserviços e APIs externas
`src/utils/`	Utilitários compartilhados (streams, etc.)