# Tecnologias Adotadas — Mud Sentinel

**Documento:** `arquitetura/02-tecnologias.md`  
**Versão:** 1.0.0  
**Status:** Vigente  
**Regra:** Alteração de item marcado como **Core** exige ADR aprovado.

---

## 1. Critérios de seleção

1. Adequação ao domínio (dados, grafo, IA, compliance).
2. Maturidade e ecossistema de segurança.
3. Contratabilidade de talentos.
4. Custo total de propriedade (licenças + ops + risco).
5. Longevidade e portabilidade.
6. Observabilidade e testabilidade.

---

## 2. Stack Core (resumo)

| Camada | Tecnologia | Classificação |
|--------|------------|---------------|
| Linguagem backend | Python 3.12+ | Core |
| Framework API | FastAPI | Core |
| Linguagem frontend | TypeScript | Core |
| Framework web | Next.js (App Router) | Core |
| OLTP | PostgreSQL 16+ | Core |
| Cache / broker leve | Redis 7+ | Core |
| Filas / jobs | Redis + ARQ ou Celery | Core |
| Busca | OpenSearch | Core |
| Grafo | PostgreSQL + Apache AGE *ou* Neo4j (ver ADR) | Core (decisão fina em ADR-004) |
| Object storage | S3-compatible | Core |
| IaC | Terraform | Core |
| Containers | Docker; orquestração Kubernetes (prod) | Core |
| CI | GitHub Actions / GitLab CI | Core |
| Observabilidade | OpenTelemetry + Prometheus + Grafana + Loki | Core |
| Auth | OAuth2/OIDC (Keycloak ou IdP managed) | Core |

---

## 3. Backend

### 3.1 Python 3.12+ + FastAPI

**Escolha.**

| | |
|--|--|
| **Vantagens** | Ecossistema dominante em dados/IA; tipagem moderna; async nativo no FastAPI; OpenAPI automático; velocidade de entrega em APIs |
| **Desvantagens** | GIL para CPU-bound (mitigado por workers/processos); tipagem menos rígida que Go/Java se disciplina falhar |
| **Por que** | O coração do produto é inteligência de dados + IA + pipelines — Python maximiza produtividade nesses eixos sem sacrificar qualidade com type hints + linters |

**Alternativas avaliadas:**

| Alternativa | Vantagens | Desvantagens | Motivo da rejeição (MVP) |
|-------------|-----------|--------------|---------------------------|
| Node.js / NestJS | Um só lenguaje com frontend | Ecossistema IA/dados mais fraco | Menos natural para ingestão/ML |
| Java / Spring | Robustez enterprise | Mais verboso; custo de time | Overkill para fase inicial |
| Go | Performance e deploys simples | Menos libs de dados/IA | Candidato a workers específicos no futuro |
| PHP / Laravel | Fit com shared hosting | Menos alinhado a grafo/IA/async workers | Marketing site ok; **não** core SaaS |

### 3.2 SQLAlchemy 2.x + Alembic

| | |
|--|--|
| **Vantagens** | ORM maduro; migrações versionadas; suporte async |
| **Desvantagens** | Curva; risco de queries N+1 |
| **Por que** | Controle fino sobre PostgreSQL e compatibilidade com Clean Architecture (repositórios) |

### 3.3 Pydantic v2

Validação de bordas (DTOs/commands). Domínio rico permanece em objetos de domínio — Pydantic não substitui o modelo de domínio.

---

## 4. Frontend

### 4.1 TypeScript + Next.js

| | |
|--|--|
| **Vantagens** | SSR/SEO para páginas públicas; App Router; ecossistema React; tipagem end-to-end com OpenAPI gerado |
| **Desvantagens** | Complexidade de caching/SSR; acoplamento ao ecossistema Vercel se mal usado |
| **Por que** | Produto B2B com área logada rica + site institucional; TypeScript reduz regressões em UI complexa (grafo) |

**UI:** biblioteca headless (Radix) + design system próprio.  
**Visualização de grafo:** biblioteca consolidada (ex.: Cytoscape.js ou Sigma.js) — ADR de frontend quando iniciar UI.

**Alternativas:** Remix, SPA Vite pura — rejeitadas por menor benefício SSR/marketing integrado.

---

## 5. Dados e armazenamento

### 5.1 PostgreSQL 16+

| | |
|--|--|
| **Vantagens** | Confiabilidade, JSONB, particionamento, RLS opcional, extensões |
| **Desvantagens** | Travessias profundas de grafo podem degradar |
| **Por que** | Fonte da verdade universal para SaaS multi-tenant auditável |

### 5.2 Camada de grafo

**Posição oficial:** capacidade de grafo é **requisito**; implementação exata em [ADR-004](../adr/0004-graph-storage.md).

| Tecnologia | Vantagens | Desvantagens |
|------------|-----------|--------------|
| Apache AGE (sobre PG) | Menos ops; SQL+Cypher; alinhado ao PG | Maturidade/ops a validar; limites de escala |
| Neo4j | Excelente para travessias; tooling | Ops extra; custo; sincronização com OLTP |
| Edge tables em SQL puro | Simplicidade inicial | Path queries custosos cedo |

### 5.3 OpenSearch

| | |
|--|--|
| **Vantagens** | Busca full-text, facetas, open-source lineage ES |
| **Desvantagens** | Cluster ops; mapeamentos sensíveis |
| **Por que** | Busca de entidades é UC-003 crítico; PG FTS insuficiente para ranking/facetas avançadas |

**Alternativa:** Meilisearch — mais simples, porém menos maduro para facetas enterprise.

### 5.4 Redis

Cache, rate limiting, broker de jobs, locks distribuídos.

### 5.5 Object storage S3-compatible

Raw de ingestão, artefatos de export. Preferir API S3 para portabilidade (AWS S3, MinIO, etc.).

---

## 6. Jobs e mensageria

**MVP:** Redis + **ARQ** ou **Celery**.

| Opção | Vantagens | Desvantagens | Indicação |
|-------|-----------|--------------|-----------|
| ARQ | Async nativo, simples | Ecossistema menor que Celery | APIs async FastAPI |
| Celery | Maduro, beat schedules | Mais peso | Schedules complexos |

**Evolução:** Kafka/Redpanda quando volume exigir log de eventos replayable (ADR futuro).  
**Por que não Kafka no dia 1:** custo cognitivo e ops sem benefício até alto volume.

---

## 7. Inteligência Artificial

| Componente | Tecnologia | Notas |
|------------|------------|-------|
| Orquestração | Camada interna própria (ports) | Não acoplar framework LLM no domínio |
| LLMs | Provedores via adapter | Multi-provider |
| Embeddings | Modelo versionado + índice vetorial | Avaliar pgvector vs. OpenSearch k-NN (ADR) |
| Avaliação | Golden sets + human feedback | Obrigatório antes de ampliar autonomia |

**Vantagens:** troca de fornecedor, controle de custo, auditoria de prompt.  
**Desvantagem:** mais código de cola inicial — aceitável pelo risco de lock-in.

---

## 8. Identidade

**OIDC/OAuth2** com provedor dedicado (Keycloak self-hosted **ou** IdP managed).

| | Keycloak | IdP managed |
|--|----------|-------------|
| Vantagens | Controle, custo previsível em escala | Menos ops, features rápidas |
| Desvantagens | Ops e upgrades | Custo/unitário + vendor |
| Uso | Preferível se compliance exigir controle | Preferível para velocidade MVP |

MFA obrigatório para papéis administrativos. SSO SAML/OIDC no plano enterprise (Fase 2).

---

## 9. Infraestrutura

| Tecnologia | Vantagens | Desvantagens | Motivo |
|------------|-----------|--------------|--------|
| Docker | Reprodução local/CI | Imagens grandes se mal feitas | Padrão de indústria |
| Kubernetes (prod) | Escala, isolamento | Complexidade | Alvo de produção |
| Terraform | Estado, review de infra | Curva HCL | Auditabilidade de mudanças de infra |

**Não adotar** dependência de shared hosting para app, DB ou workers do core SaaS.

---

## 10. Observabilidade e qualidade

| Ferramenta | Função |
|------------|--------|
| OpenTelemetry | Traces/metrics/logs correlation |
| Prometheus + Grafana | Métricas e dashboards |
| Loki (ou equivalente) | Agregação de logs |
| Sentry (ou equivalente) | Error tracking |
| pytest + coverage | Testes backend |
| Playwright / Testing Library | E2E / UI |
| ruff + mypy | Lint/tipos Python |
| eslint + tsc | Lint/tipos TS |
| gitleaks / Trivy | Segredos e vulnerabilidades de imagem |

---

## 11. Pacote explícito “não usar no core”

| Tecnologia | Motivo |
|------------|--------|
| MongoDB como fonte da verdade | Modelo relacional + auditoria favorável ao PG |
| Firebase como backend principal | Lock-in e modelo de segurança inadequado |
| Laravel no core SaaS | Ecossistema IA/dados inferior para este produto |
| Microserviços sem métrica | Complexidade prematura |

---

## 12. Política de atualização

- Versões LTS/stable apenas em produção.
- Patches de segurança: SLA interno ≤ 7 dias para críticas.
- Upgrades major: spike + ADR se afetar Core.