Arquitetura

Documento humano. A arquitetura-alvo detalhada (com diagramas e ADRs) vive em .claude/docs/architecture.md e .claude/docs/decisions.md. Esta página resume para o time.

Princípios

1. API-first — contrato (OpenAPI) antes da implementação; renderizado no Scalar.
2. Multiorganização em tudo — orgId em dados, tokens e (futuramente) eventos/logs.
3. Stateless — serviços escalam por réplicas; estado em PostgreSQL/Redis.
4. Configuração > código — integrações e regras de negócio configuráveis (alvo).
5. Orientado a eventos — extensão por novos consumidores (adoção incremental).

Estado atual vs alvo

• Hoje: um backend NestJS modular (módulos por bounded context) + Next.js + Docs, tudo em containers. Isolamento por organização via orgId na aplicação.
• Alvo: extração de módulos em microsserviços, RLS no PostgreSQL, Kafka + outbox para eventos, observabilidade completa (OpenTelemetry). Adotado por etapas conforme o volume.

Módulos (bounded contexts)

• Identity & Access — organizações, usuários, papéis/permissões (RBAC), empresas/equipes.
• Commercial — clientes, produtos, preços, pagamentos, pedidos (planejado).
• Integration Platform — fontes, conectores REST, auth plugável, sync (planejado).
• Order Processing — pipeline pré/pós + engine de regras (planejado).

Multiorganização

orgId em toda tabela de negócio. Chaves únicas compostas com orgId (ex.: (orgId, email)). A organização é resolvida a partir do token e, na evolução, será imposta por Row-Level Security no banco.

Execução / escala

Tudo containerizado (Docker). Serviços stateless → escalam horizontalmente atrás de um load balancer. docker-compose para dev; pronto para Kubernetes.