ADRs — Architecture Decision Records
Um ADR registra uma decisão de arquitetura: o porquê de uma escolha, com contexto, alternativas e consequências. É append-only — não se reescreve; se a decisão muda, cria-se um novo ADR que supersede o anterior.
Numeração: os ADRs 0001–0005 são herdados do monolito legado
bmp-novo-produto-dadose estão importados abaixo em Legado. O ADR-0006 (segregação em api/web) é referenciado no código mas não tem arquivo no log legado (fantasma). Os ADRs desta plataforma continuam a sequência a partir de 0007.
Log de decisões (desta plataforma)
| ADR | Título | Status | Specs relacionadas |
|---|---|---|---|
| 0007 | Logging estruturado via @npd/common | Accepted | spec-001 |
| 0008 | Componentes de UI via @nuclea/ui | Accepted | spec-002 |
| 0009 | Definition of Done: docs + testes por spec | Accepted | todas |
| 0010 | Processo: Forge spec-driven + papéis HITL | Accepted | todas |
| 0011 | Branching + Continuous Delivery (dev/uat/prod) | Accepted | (CI/CD) |
| 0012 | Keycloak como IDM (realm npd + token exchange) | Accepted | spec-004 |
| 0013 | Isolamento de tenant por subdomínio | Accepted | spec-004 |
| 0014 | Políticas de risco versionadas (regra vira dado) | Accepted | spec-004 |
| 0015 | Navegação consolidada do backoffice | Accepted | spec-004 |
| 0016 | Papéis acumulativos de operação | Accepted | spec-006 |
| 0017 | Dossiê consolidado: sem dado ⇒ nota, nunca número | Accepted | spec-006 |
| 0018 | Cliente pertence ao tenant, não à carteira | Accepted | spec-007 |
| 0019 | FIDC como cliente da asset | Accepted | spec-007 |
| 0020 | Parecer com dupla instância (analista + comitê) | Accepted | spec-007 |
| 0021 | Política de risco: catálogo, faixas e uso no dossiê | Accepted | spec-008 |
| 0022 | Contrato de faixas: o produto define a régua, o tenant só homologa os cortes | Accepted | spec-008 |
| 0023 | A emissão de dossiê como fato persistido | Accepted | spec-009 |
| 0024 | Autoliquidação é faixa: exibir a da fonte e classificar pelo piso | Accepted | chamado de campo |
| 0025 | Consulta que falha não é ausência de restrição | Accepted | backlog de validação |
| 0026 | O insight acompanha o dossiê; não vence com o relógio | Accepted | backlog de validação |
Processo: o ADR-0009 define que toda spec alimenta a documentação (abas Arquitetura/Funcionamento/Observabilidade), os testes unitários e os E2E — e que toda documentação markdown gerada entra neste site.
Legado (herdados do monolito bmp-novo-produto-dados)
Registro histórico append-only; referenciam o stack antigo (Next.js/Vercel).
| ADR | Título | Status |
|---|---|---|
| 0001 | Adoção do formato ADR | Aceito |
| 0002 | Lock de stack (Next.js/Supabase/Vercel) | Aceito |
| 0003 | Lock de provider LLM (Anthropic) | Superseded by 0005 |
| 0004 | Compressão do SDLC (demo 15/05) | Aceito |
| 0005 | LLM multi-provider (Anthropic + OpenAI) | Proposto |
| 0006 | Segregação do monolito → api/web | referenciado, sem arquivo (fantasma) |
ADR × Spec
- ADR = a decisão (política/direção) e o porquê — imutável.
- Spec = o que construir para aplicar a decisão (requisitos, critérios) — evolui.
- Fluxo:
ADR → spec → plan → tasks → código. Às vezes a spec vem antes e, no planejamento, gera novos ADRs.
Template
Copie para docs/adr/ADR-NNNN-titulo.md e preencha:
---
sidebar_position: N
title: "ADR-NNNN — Título curto da decisão"
---
# ADR-NNNN — Título curto da decisão
**Status:** Proposed | Accepted | Superseded by ADR-XXXX
**Data:** AAAA-MM-DD
## Contexto
O problema, as forças e restrições que motivam a decisão.
## Decisão
O que foi decidido (voz imperativa).
## Consequências
Trade-offs: o que fica mais fácil (+) e mais difícil (−).
## Alternativas consideradas
O que foi descartado e por quê.
## Specs relacionadas
- [spec-XYZ](../specs/spec-XYZ.md)