Decisões de arquitetura (ADR)

Registro enxuto das decisões estruturais e o porquê.

ADR-001 — Monólito modular (não microserviços)

Decisão: 1 front + 1 back organizados por módulos, shell/core comum. Por quê: simplicidade operacional; o overhead de microserviços não se justifica no estágio. Migração de microserviços é possível depois se um módulo exigir escala isolada.

ADR-002 — Multi-tenant desde a fundação

Decisão: tenant_id em toda entidade de negócio + tenant.modules. Por quê: custo baixo agora, caro depois; mantém a rota SaaS aberta.

ADR-003 — UUID como PK

Decisão: UUID + (opcional) código legível. Por quê: unicidade global, seguro, sem colisão entre tenants. Os ids curtos do mock (cd,l1) eram só demo.

ADR-004 — Contrato camelCase ponta a ponta

Decisão: o back serializa camelCase (Pydantic to_camel); o front consome direto. Por quê: o front já falava camelCase; evita um mapper em cada chamada. (Bug pego e corrigido: o módulo de auth nascera snake_case e foi unificado.)

ADR-005 — Build dentro do docker build

Decisão: a imagem é construída via docker build (RAM do host), não no script do job. Por quê: o runner Swarm limita o job a 1 GiB — insuficiente para o build SSR (OOM). Mesmo padrão do pipelines/nodejs.yml. (Também corrigimos o python.yml para tagear a imagem com PIPELINE_IID, casando build e deploy.)

ADR-006 — Documentação: VitePress + OpenAPI

Decisão: doc geral em VitePress; referência de API gerada do FastAPI (OpenAPI). Por quê: doc geral curada + referência sempre fiel ao código, sem manutenção manual.

Em aberto (ver ARQUITETURA.md no repo do back)

• Nome do produto-mãe ("Aby's OS"?).
• Namespacear rotas (/remanejamento/*) já ou no 2º módulo.
• Reorganizar pastas core/modules junto com a migração das telas, ou depois.
• Ordem dos próximos módulos (Vendas tende a ser o 1º — fecha o loop de métricas).