Arquitetura Backend
Exceções pragmáticas
Desvios conscientes da arquitetura e quando criar um Gateway
A arquitetura é consistente na maior parte do código, mas existem desvios conscientes que o time deve conhecer.
| Integração | Como é injetada | Observação |
|---|---|---|
| AWS S3 | AWSS3Service direto | Não existe S3Gateway em app/gateways/ |
| Microserviços | *Service em src/external/ | Registrados em SERVICES do HTTPModule; sem gateway |
| Configuração | EnvConfig import estático | Sem ConfigModule / ConfigGateway |
| Helpers Knex | Import de infra/database/knex/utils | Usados em use cases e consumers |
Quando criar um novo Gateway
Crie um gateway abstrato quando:
- A dependência é crítica para testes (mock no use case).
- Há mais de uma implementação possível ou provável.
- A dependência é usada em múltiplos use cases e representa um port de negócio (e-mail, fila, cripto).
Aceite injeção direta quando:
- É um adapter HTTP único e estável (
CustomerService→ microserviço). - O escopo é restrito a um use case e testes mockam o service, não o gateway.
- A equipe avalia que o custo do gateway não compensa (ex.: S3 hoje).
External services
src/external/microservices/ e src/external/google/:
- Classes
@Injectable()com Axios. - URLs base em
EnvConfig. - Tipos em
types/*.d.tspor serviço.
Exemplos: CustomerService, ProductService, OmieService, MapsService.