# Arquitetura Geral — Mud Sentinel **Documento:** `arquitetura/01-arquitetura-geral.md` **Versão:** 1.0.0 **Status:** Vigente --- ## 1. Objetivo Definir a visão arquitetural de longo prazo do Mud Sentinel: modular, segura, auditável, observável e preparada para evolução por muitos anos — sem acoplar o domínio a frameworks, provedores de nuvem ou modelos de IA específicos. --- ## 2. Estilo arquitetural **Estilo principal:** Modular Monolith (application core) + workers assíncronos + serviços satélite quando o custo de acoplamento justificar. **Justificativa:** | Abordagem | Vantagens | Desvantagens | Decisão | |-----------|-----------|--------------|---------| | Microserviços desde o dia 1 | Escala independente, isolation | Complexidade ops, latência, inconsistência distribuída | **Rejeitado no MVP** | | Monólito modular | Deploy simples, transações locais, refatoração barata | Risco de erosão de limites se disciplina falhar | **Adotado** | | Serverless-only | Escala elástica | Cold start, vendor lock, debugging de workflows longos | **Complementar** (jobs pontuais), não core | **Regra de ouro:** Começar monólito modular com boundaries DDD explícitos; extrair serviço apenas com ADR e métricas que justifiquem (throughput, ciclo de release independente, isolamento de falha). --- ## 3. Diagrama lógico (alto nível) ```text ┌──────────────────────────────────────────────────────────────────────────┐ │ Clientes │ │ Web App (SPA/SSR) │ API Consumers (M2M) │ Admin Ops │ └──────────────┬─────────────────┬──────────────────────┬──────────────────┘ │ HTTPS/TLS │ │ ▼ ▼ ▼ ┌──────────────────────────────────────────────────────────────────────────┐ │ Edge / API Gateway / WAF │ │ Rate limit │ TLS │ WAF │ Bot control │ └───────────────────────────────┬──────────────────────────────────────────┘ ▼ ┌──────────────────────────────────────────────────────────────────────────┐ │ BFF / API Application (Modular Monolith) │ │ ┌─────────┐ ┌──────────┐ ┌───────┐ ┌──────┐ ┌────┐ ┌───────┐ ┌────────┐ │ │ │Identity │ │ Catalog │ │ Graph │ │Cases │ │Risk│ │ AI │ │Billing │ │ │ │& Access │ │& Search │ │ │ │ │ │ │ │Orchestr│ │ │ │ │ └─────────┘ └──────────┘ └───────┘ └──────┘ └────┘ └───────┘ └────────┘ │ │ ┌────────────────────────────────────────────────────────────────────┐ │ │ │ Shared Kernel: Audit │ Observability │ Tenancy │ │ │ └────────────────────────────────────────────────────────────────────┘ │ └───────────────┬───────────────────┬───────────────────┬──────────────────┘ │ │ │ ┌───────▼──────┐ ┌───────▼──────┐ ┌───────▼──────┐ │ PostgreSQL │ │ Graph Store │ │ Search Index │ │ (OLTP+JSON) │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ ┌───────▼──────────────────────────────────────────────────────────┐ │ Message Bus / Queue │ │ ingestion.* │ analysis.* │ notify.* │ audit.mirror │ └───────┬───────────────────┬───────────────────┬──────────────────┘ ▼ ▼ ▼ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Ingestion │ │ AI / Analytics│ │ Notifiers │ │ Workers │ │ Workers │ │ Workers │ └──────┬───────┘ └──────┬───────┘ └──────────────┘ ▼ ▼ ┌──────────────┐ ┌──────────────┐ │ Object Store │ │ Model APIs │ │ (raw/Artifacts)│ │ (LLM/Embed) │ └──────────────┘ └──────────────┘ ``` --- ## 4. Bounded contexts (DDD) | Contexto | Responsabilidade | Linguagem ubíqua (exemplos) | |----------|------------------|-----------------------------| | **Identity & Access** | Usuários, authn/authz, MFA, SSO | Subject, Role, Permission, Session | | **Tenancy** | Organizações, planos, isolation keys | Tenant, Workspace, Quota | | **Catalog** | Entidades, atributos, versões, lineage | Entity, Attribute, SourceRecord, Snapshot | | **Search** | Indexação e consulta textual/facetas | Document, Hit, Facet | | **Graph** | Nós, arestas, travessias, paths | Node, Edge, Path, Expansion | | **Ingestion** | Conectores, jobs, validação, publicação | Connector, IngestRun, DeadLetter | | **Risk** | Regras, scores, explicações | Rule, Factor, Score, Threshold | | **Cases** | Dossiês, estados, exports | Case, Finding, ExportManifest | | **AI Orchestration** | Prompts, modelos, grounding, saídas | PromptTemplate, Completion, Citation | | **Billing** | Assinaturas, uso, invoices | Plan, Entitlement, UsageEvent | | **Audit** | Trilha append-only, retenção | AuditEvent, Actor, Resource | | **Notification** | Canais de alerta | Notification, Channel, Preference | **Shared Kernel (mínimo):** `TenantId`, `ActorId`, `CorrelationId`, erros tipados, contratos de auditoria. **Anti-corruption layers (ACL):** nas bordas de fontes públicas, provedores de pagamento, IdP e LLMs. --- ## 5. Camadas (Clean Architecture) Dentro de cada módulo de aplicação: ```text Adapters (HTTP, Persistence, Messaging, LLM providers) ↓ depende de Application (use cases / application services / ports) ↓ depende de Domain (entities, value objects, domain events, policies) ``` **Regra:** Domínio **não** importa frameworks, ORM, SDK de cloud ou cliente HTTP. **Justificativa:** Longevidade — troca de ORM, broker ou provedor de IA sem reescrever regras de negócio. Detalhamento: [Clean, SOLID e DDD](05-clean-solid-ddd.md). --- ## 6. Multi-tenancy **Modelo adotado:** *Pool* (schema/database compartilhados) com `tenant_id` obrigatório em todas as tabelas de negócio + enforcement em repositórios e políticas de autorização. | Modelo | Vantagens | Desvantagens | Decisão | |--------|-----------|--------------|---------| | DB por tenant | Isolamento forte | Ops cara, migrações N× | Opcional enterprise futuro (ADR) | | Schema por tenant | Isolamento médio | Complexidade migração | Sob demanda | | Pool + tenant_id | Simples, barato, analítico unificado | Risco de bug cross-tenant | **Padrão** + testes de isolamento obrigatórios | **Controles compensatórios:** row-level guards, testes automatizados de vazamento, revisão de queries raw, observabilidade de `tenant_id` ausente (alerta). --- ## 7. Dados: responsabilidades | Store | Uso | Por quê | |-------|-----|---------| | PostgreSQL | Fonte da verdade OLTP, casos, IAM metadata, billing | ACID, maturidade, JSONB, extensões | | Graph store | Travessias e padrões de relacionamento | Consultas de profundidade ineficientes em SQL puro em escala | | Search engine | Busca full-text / facetas | UX e ranking | | Object storage | Raw dumps, artefatos de export, anexos | Custo e volume | | Redis | Cache, rate limit, locks, filas leves | Latência e coordenação | | Append-only audit store | Trilha (pode ser tabela PG particionada ou stream) | Imutabilidade lógica | --- ## 8. Sincronismo vs. assíncrono | Operação | Modo | Motivo | |----------|------|--------| | Login, CRUD leve, leitura ficha | Síncrono | UX | | Ingestão de fontes | Assíncrono | Volume / retry | | Expansão pesada de grafo / path | Assíncrono ou timeout curto + job | Proteção de latência | | Completions de IA | Assíncrono preferencial; sync curto com timeout | Custo e falhas de provedor | | Fan-out de alertas | Assíncrono | Resiliência | Ver [Event-Driven Architecture](06-event-driven.md). --- ## 9. Segurança na arquitetura - Zero trust interno progressivo: autenticação em toda borda; autorização no application boundary. - Segredos apenas em vault/secret manager; nunca em git. - Criptografia em trânsito (TLS 1.2+) e em repouso (volumes/buckets). - Separação de papéis: analista ≠ admin ≠ plataforma. - Dados classificados; campos sensíveis mascarados em logs. Ver [Segurança](../operacao/01-seguranca.md). --- ## 10. Ambientes | Ambiente | Propósito | |----------|-----------| | Local | Dev com compose; dados sintéticos | | Staging | Homologação; integração real sandbox | | Production | Tráfego real; mudança via pipeline | Marketing site estático pode residir em hosting web convencional; **o core SaaS não deve depender de shared hosting** para banco, filas ou workers. **Justificativa:** Isolamento de performance, segurança e escala — requisito de produto de conformidade. --- ## 11. Qualidade arquitetural — atributos | Atributo | Abordagem | |----------|-----------| | Escalabilidade | Horizontal em API stateless + workers; stores vertical/horizontal conforme perfil | | Disponibilidade | Multi-AZ; health checks; degradar IA antes de degradar busca core | | Manutenibilidade | Módulos, testes, ADRs, linguagem ubíqua | | Auditabilidade | Contexto Audit como cidadão de primeira classe | | Portabilidade | Ports/adapters; IaC; evitar APIs proprietárias no domínio | | Performance | Orçamentos de latência por endpoint; quotas de travessia | --- ## 12. Evolução Extração típica (quando justificada por ADR): 1. Workers de ingestão → serviço `ingestion`. 2. AI orchestration → serviço com sandbox de prompts. 3. Graph query API → serviço dedicado se CPU/memória isoladas forem necessárias. Até lá, packages/módulos no monólito com boundaries lintados (ex.: regras de import entre camadas).