Pular para o conteúdo principal

Status: Approved · v2 · SPEC-ARCH-BACKEND-001

depends_on: SPEC-API-OVERVIEW-001, SPEC-DOMAIN-BASE-001

used_by: IS-ZERO-00.3, IS-MVP-01.1

Arquitetura backend NestJS

Backend modular, orientado a casos de uso e protegido contra controllers/repositories com regras indevidas.

Camadas e módulos​

Camadas​

Controller
  → Application Service / Use Case
  → Domain policy/service quando necessário
  → Repository/Provider interfaces
  → Infrastructure adapters

Controllers validam transporte, aplicam guards e chamam casos de uso; não acessam ORM nem calculam domínio. Application services controlam transação, idempotência, persistência, audit e side effects. Domain services são puros sempre que possível. Repositories não notificam nem decidem regra.

Estrutura NestJS​

services/api/src/
  main.ts
  app.module.ts
  common/
    guards/
    filters/
    interceptors/
    idempotency/
    audit/
  modules/<domain>/
    presentation/
    application/
    domain/
    infrastructure/

Providers​

Pix, storage, notification, email, clock e ID generator são interfaces. MVP possui fake adapters; implementação externa não contamina caso de uso.

Persistência​

Banco real não é requisito do starter, mas repositories já expressam operações necessárias sem abstração genérica BaseRepository. Transações são orientadas a caso de uso.

Cross-cutting​

  • Global prefix /api/v1.
  • Validation pipe runtime na API, separado dos contracts.
  • Response interceptor e exception filter implementam envelope.
  • RequestId middleware.
  • Permission/idempotency/audit services transversais.

Eventos e jobs​

  • Eventos internos síncronos no início quando suficiente.
  • Jobs: payment expiry, credit expiry, match auto-validation, sponsor expiry.
  • Todo job é idempotente, usa clock injetado e registra resultado.
  • Fila distribuída só com necessidade.

Testes​

  • Domain unit tests.
  • Use cases com repositories/providers fake.
  • Controller integration para envelope/guards.
  • Financial/idempotency transactional tests antes de produção.

Critérios de aceite​

  • Controller pequeno.
  • Nenhuma entity ORM em response.
  • Provider externo atrás de interface.
  • Permission/audit/idempotency aplicados conforme spec.