Arquitetura

A API segue uma organização Clean Architecture / DDD-lite, separando domain (regras de negócio) de infra (HTTP, banco, cache, ambiente).

Camadas

• core — utilitários transversais: o tipo Either (usado pelos use-cases para retornar Left/Right em vez de lançar exceções), entidades base e erros de domínio.
• domain — cada subdomínio (auth, user, tenancy, logger) contém application (use-cases, repositórios, decorators) e enterprise (entidades).
• infra — adapta o domínio ao mundo externo: controllers HTTP, Prisma, Redis e validação de ambiente.

Módulos NestJS

O AppModule monta os middlewares de autenticação e registra o PermissionGuard globalmente via APP_GUARD.

Ciclo de vida de uma requisição

O trajeto de um request em /api/* passa por middleware de autenticação, guard de permissão, pipe de validação (Zod), use-case e presenter.

Padrão dos controllers

Cada operação HTTP é um controller dedicado (um arquivo por caso de uso: create-user, fetch-users, edit-user, ...). Padrões recorrentes:

• Validação — ZodValidationPipe com um schema Zod declarado no próprio arquivo; o mesmo schema alimenta o Swagger via zodToSwaggerSchema.
• Autorização — decorator @Permissions(Resource, Scope).
• Auditoria — decorator @AuditLog(action, entity) em operações de escrita.
• Saída — um Presenter (UserPresenter, TenantPresenter, ...) converte a entidade de domínio no formato HTTP.
• Erros de domínio — o use-case devolve Either; o controller traduz Left em exceções HTTP (ex.: ConflictException).