# ADR-0004 — Estratégia de armazenamento de grafo

**Status:** Accepted (direção); spike de validação obrigatório antes do lock-in definitivo  
**Data:** 2026-07-14  
**Decisores:** Arquitetura de Software

---

## Contexto

Análise de relacionamentos é diferencial do produto (UC-005, UC-006). SQL puro com tabelas de arestas funciona no início, mas path finding e expansões profundas degradam. Introduzir Neo4j cedo aumenta custo operacional e problemade dual-write.

## Decisão

1. **Modelo canônico de relacionamento** permanece no domínio Catalog/Graph com persistência inicial em PostgreSQL (edge tables) para o MVP piloto, **ou** Apache AGE se o spike (≥ 2 semanas) demonstrar estabilidade operacional no ambiente alvo.
2. **Critério de promoção a Neo4j (ou serviço de grafo dedicado):** quando p95 de travessias P0 exceder orçamento **após** otimização de índices/limites de profundidade, ou quando path queries se tornarem requisito comercial bloqueante.
3. Qualquer dual-write Graph Store ⇔ PostgreSQL exige outbox + reconciliação.

## Alternativas consideradas

| Opção | Prós | Contras | Avaliação |
|--------|------|---------|-----------|
| Somente edge tables PG | Simples | Path queries caros | Aceitável MVP controlado |
| Apache AGE | Cypher no PG; menos ops | Maturidade/ops a validar | Preferido se spike OK |
| Neo4j desde dia 1 | Excelente travessia | Ops, custo, sync | Adiar até métrica |
| Amazon Neptune etc. | Managed | Lock-in | Avaliar só com cloud strategy |

## Consequências

### Positivas
- Evita overengineering e sync prematuro.
- Mantém SoR claro.
- Critérios objetivos para evolução.

### Negativas / riscos
- Possível migração de dados de arestas no futuro.
- Spike AGE pode concluir negativamente → permanece SQL + limites de produto.

### Follow-ups
- [ ] Spike AGE vs edge tables com datasets sintéticos.
- [ ] Definir limites de profundidade/fan-out no product.

## Referências

- [Tecnologias](../arquitetura/02-tecnologias.md)
- [Casos de Uso](../produto/02-casos-de-uso.md)