# Clean Architecture, SOLID e DDD — Mud Sentinel

**Documento:** `arquitetura/05-clean-solid-ddd.md`  
**Versão:** 1.0.0  
**Status:** Vigente

---

## 1. Objetivo

Tornar obrigatório o uso coordenado de **Clean Architecture**, **SOLID** e **Domain-Driven Design** para preservar o domínio de inteligência e compliance ao longo de anos de evolução tecnológica.

---

## 2. Clean Architecture

### 2.1 Regra de dependência

Dependências apontam **somente para dentro** (em direção ao domínio).

```text
Frameworks & Drivers  →  Interface Adapters  →  Application  →  Domain
```

### 2.2 Responsabilidades

| Camada | Contém | Não contém |
|--------|--------|------------|
| Domain | Entidades, VOs, invariantes, domain events, policies | SQL, HTTP, SDKs, Pydantic de request |
| Application | Casos de uso, orquestração, ports, transações de app | Detalhes de framework web |
| Adapters | ORM models, routers, fila, LLM clients | Regras de negócio novas |
| Composition root | DI wiring | Lógica |

### 2.3 Justificativa

O produto trocará provedores de IA, brokers e possivelmente o store de grafo. Sem fronteiras limpas, cada troca vira reescrita. Em domínio regulado, testes de invariantes no domínio reduzem risco de regressão silenciosa.

### 2.4 Trade-offs

| Vantagens | Desvantagens |
|-----------|--------------|
| Testabilidade alta | Mais arquivos/tipos no início |
| Independência de framework | Exige disciplina do time |
| Longevidade | Custo de mapping DTO ↔ domínio |

**Mitigação do custo:** generators/templates de módulo; não abreviações “só dessa vez”.

---

## 3. SOLID — aplicação obrigatória

### S — Single Responsibility

Um caso de uso = uma intenção de negócio. Routers não validam política de risco. Conectores não gravam dossiês.

### O — Open/Closed

Novas fontes = novo conector. Novas regras de risco = nova regra plugável. Evitar modificar core a cada fonte.

### L — Liskov Substitution

Implementações de ports (repositórios, providers) devem honrar contratos (incl. erros tipados). Testes de contrato obrigatórios para adapters críticos.

### I — Interface Segregation

Ports pequenos (`CaseRepository`, `CaseExportWriter`) em vez de `GodRepository`.

### D — Dependency Inversion

Application define ports; infrastructure implementa. Domínio não conhece FastAPI/SQLAlchemy.

**Justificativa conjunta:** SOLID operacionaliza Clean Architecture no dia a dia de PRs.

---

## 4. Domain-Driven Design

### 4.1 Linguagem ubíqua

Termos oficiais (PT-BR no negócio; identificadores EN no código — ver convenções):

| Termo | Significado |
|-------|-------------|
| Entity | Nó de catálogo (pessoa, organização, etc.) |
| Edge / Relationship | Vínculo tipado e datado |
| Case / Dossier | Agregação analítica auditável |
| SourceRecord | Evidência bruta versionada |
| Score | Resultado explicável de Risk |
| Completion | Saída de IA orquestrada |

Conflitos de significado entre contextos → Context Mapping documentado.

### 4.2 Aggregates (diretrizes)

| Aggregate root (exemplos) | Invariantes típicos |
|---------------------------|---------------------|
| `Tenant` | Quotas não negativas; status válido |
| `Case` | Transições de estado permitidas; pertence a um tenant |
| `IngestRun` | Estados de pipeline; idempotency key |
| `EntitySnapshot` | Lineage obrigatório |

**Regra:** modificar aggregate apenas via métodos de domínio / application service do dono; sem “setters anêmicos” espalhados.

### 4.3 Domain Events

Usar para fatos relevantes (`CaseFinalized`, `IngestRunPublished`, `EntityGraphUpdated`).  
Payloads versionados; sem PII desnecessária.

### 4.4 Anti-Corruption Layer

Toda integração externa (Receita-like dumps, LLM, Stripe-like billing, IdP) passa por ACL que traduz para o modelo interno.

### 4.5 Strategic design

- **Core domain:** Graph + Catalog lineage + Cases + Auditability + AI grounding.
- **Supporting:** Billing, Notify, Search indexing.
- **Generic:** IAM patterns (ainda assim bem feitos).

Investir excelência de modelagem no core domain primeiro.

---

## 5. Modelo anêmico vs. rico

**Preferir modelo rico** no core domain (invariantes encapsuladas).  
DTOs anêmicos são aceitáveis nas bordas.

**Justificativa:** regras de compliance espalhadas em services proceduralmente geram bypass e bugs de auditoria.

---

## 6. Checklist de PR (arquitetura)

- [ ] Regra nova está no domínio/application corretos?
- [ ] Algum import viola boundary?
- [ ] Evento de auditoria necessário foi previsto?
- [ ] Teste de domínio cobre invariante?
- [ ] Nome alinha à linguagem ubíqua?

PRs que violem Clean/SOLID/DDD sem justificativa registrada devem ser rejeitados.