> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Arquitetura > Conheça o monolito modular do Matcher, construído sobre DDD, arquitetura hexagonal e CQRS, com sete contextos delimitados que evoluem de forma independente. O Matcher é um **monolito modular** com Domain-Driven Design (DDD) e arquitetura hexagonal. O CQRS separa comandos (escritas) de consultas (leituras). Isso mantém a operação simples e preserva fronteiras claras. Cada módulo pode evoluir de forma independente sem a complexidade de microsserviços. ## Visão geral da arquitetura *** Arquitetura do Matcher ## Contextos delimitados *** O Matcher tem sete módulos. Cada um é dono dos seus dados e expõe interfaces limpas para os outros. * **Configuração**: o que você concilia (contextos, fontes, mapas de campos, regras) * **Discovery**: conexões com fontes de dados externas, detecção de schema e orquestração de extração com o motor de extração embutido do Matcher * **Ingestão**: entrada dos dados (parsing, validação, normalização) * **Correspondência**: o motor (execução de regras, pontuação de confiança) * **Exceção**: tratamento de itens não conciliados (workflow, roteamento, resolução) * **Governança**: trilhas de auditoria (logs imutáveis para conformidade) * **Relatórios**: visibilidade (relatórios, exportações, dashboards) ### Configuração Define **o que** você concilia e **como**. **Trata:** * Contextos (o que você concilia) * Fontes (de onde os dados vêm) * Mapas de campos (tradução de campos externos) * Regras (como corresponder) **Modelos principais:** * `ReconciliationContext`: o escopo da conciliação * `ReconciliationSource`: configuração da fonte * `FieldMap`: regras de tradução de campos * `MatchRule`: lógica de correspondência ### Discovery O contexto delimitado Discovery gerencia a conectividade com fontes de dados externas, a detecção de schema e a orquestração de extração com o motor de extração. O Discovery roda dentro do Matcher. Não existe um serviço de extração separado para fazer deploy. **Responsabilidades:** * Gerenciar conexões com fontes de dados externas * Detectar e guardar em cache os schemas das fontes * Rodar extrações no próprio processo e entregar os resultados direto para a Ingestão * Acompanhar os ciclos de vida de conexão e de extração **Entidades principais:** * `FetcherConnection`: conexão com fonte externa gerenciada localmente pelo motor de extração * `ExtractionRequest`: acompanha um ciclo de vida de extração rodado pelo motor embutido Veja [Discovery](/pt/products/matcher/integrations/matcher-discovery) para saber como o Discovery conecta a bancos de dados externos com o motor de extração. ### Ingestão O contexto delimitado de Ingestão trata a entrada e a normalização dos dados. **Responsabilidades:** * Fazer o parse dos arquivos enviados (CSV, JSON, XML) * Validar os dados recebidos contra os schemas configurados * Normalizar dados externos em uma representação canônica * Detectar e tratar registros duplicados * Emitir eventos de domínio quando a ingestão termina **Entidades principais:** * `IngestionJob`: acompanha o ciclo de vida e o status da ingestão * `Transaction`: registro canônico e normalizado de transação **Eventos publicados:** * `ingestion.completed`: indica que os dados estão prontos para a correspondência ### Correspondência O contexto delimitado de Correspondência contém o motor de conciliação. **Responsabilidades:** * Carregar as regras aplicáveis a um contexto de conciliação * Executar estratégias de correspondência (exata, por tolerância, difusa, por data) * Calcular pontuações de confiança * Criar grupos de correspondência e alocar transações * Identificar transações não conciliadas **Entidades principais:** * `MatchRun`: execução de um job de correspondência * `MatchGroup`: grupo de transações conciliadas * `MatchItem`: alocação de uma transação individual **Eventos publicados:** * `match_group.confirmed`: um grupo de correspondência foi finalizado * `match_group.unmatched`: uma correspondência confirmada antes foi revertida * `transaction.pending_review`: um candidato não automático precisa de revisão ### Gestão de exceções O contexto delimitado de Exceção gerencia transações não resolvidas. **Responsabilidades:** * Classificar exceções por severidade * Rotear exceções para times internos ou sistemas externos * Oferecer suporte a substituições e ajustes manuais * Acompanhar o status de resolução e os SLAs * Integrar com ferramentas externas de workflow **Entidades principais:** * `Exception`: uma transação não resolvida * `Resolution`: resultado do tratamento da exceção * `RoutingRule`: lógica de roteamento e escalonamento **Integrações:** * JIRA para acompanhamento de chamados * ServiceNow para incidentes da Table API * Webhooks para workflows personalizados O conector do ServiceNow cria incidentes da Table API depois que você o configura. Ele usa uma única tentativa de criação porque uma requisição repetida poderia criar um incidente duplicado. ### Governança O contexto delimitado de Governança preserva a rastreabilidade da conciliação. **Responsabilidades:** * Registrar em logs de auditoria imutáveis os workflows de mutação auditáveis e instrumentados * Fornecer histórico de auditoria consultável * Oferecer suporte a relatórios regulatórios e de conformidade **Entidades principais:** * `AuditLog`: registro append-only dos workflows de mutação auditáveis e instrumentados Os logs de auditoria são append-only por design. Ninguém pode alterar ou remover entradas. Esse design preserva a integridade para conformidade. ### Relatórios O contexto delimitado de Relatórios fornece visibilidade operacional. **Responsabilidades:** * Gerar relatórios de conciliação * Expor métricas de dashboard * Exportar dados de conciliação em vários formatos **Entidades principais:** * `Report`: resumo da conciliação * `Dashboard`: métricas operacionais agregadas * `ExportJob`: execução assíncrona de exportação ## Fluxo de dados *** A conciliação segue um pipeline determinístico entre os contextos delimitados: Você define contextos de conciliação, fontes, mapeamentos de campos e regras pela API. O Discovery conecta a fontes externas, detecta os schemas delas e roda extrações no próprio processo com o motor de extração. O Discovery entrega os resultados extraídos direto para a Ingestão. A Ingestão faz o parse, valida, normaliza e deduplica os arquivos enviados e os dados que o Discovery extrai. A Ingestão emite um evento `ingestion.completed`. A Correspondência aplica regras às transações elegíveis e produz grupos de correspondência com pontuações de confiança em uma escala inteira de 0 a 100. Grupos EXACT e TOLERANCE com confiança de pelo menos 90 em 100 podem se autoconfirmar. Grupos FUZZY e DATE\_LAG sempre exigem revisão manual. Itens não conciliados viram exceções. O contexto de Exceção classifica e roteia as exceções. A resolução acontece manualmente ou por sistemas externos. As atualizações de resolução voltam para o Matcher. A Governança registra em logs de auditoria imutáveis os workflows de mutação auditáveis e instrumentados de todo o pipeline. Os usuários acessam relatórios e dashboards que mostram o status da conciliação, as taxas de correspondência e o envelhecimento das exceções. ## Componentes de infraestrutura *** O Matcher depende dos seguintes serviços de infraestrutura: | Componente | Finalidade | Uso | | --------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------- | | **PostgreSQL** | Armazenamento principal de dados | Dados de domínio; deploys multi-tenant configurados resolvem um pool para cada tenant | | **Valkey (compatível com Redis)** | Cache e coordenação | Deduplicação, locks, chaves de idempotência | | **Backbone de streaming** | Publicação de eventos de negócio | Eventos de domínio publicados via lib-streaming | | **RabbitMQ** | Filas de infraestrutura | Filas internas de trabalho e tratamento de dead-letter | | **Systemplane** | Configuração em tempo de execução | Ajustes com hot reload sem reiniciar, pela API admin `/system/matcher/:key` | ### Arquitetura de banco de dados * **Resolução de pool por tenant** em deploys multi-tenant configurados, para separação de dados * **Consistência forte** para o estado de correspondência e de exceção * **Consistência eventual** para as visões de relatório ### Multi-tenancy O Matcher aplica isolamento estrito de tenant: * Em deploys multi-tenant com `AUTH_PROVIDER=plugin-auth`, o Matcher tira a identidade do tenant das claims `tenant_id` ou `tenantId` do JWT * Deploys single-tenant e com autenticação desabilitada usam o tenant padrão configurado * O Matcher nunca aceita identificadores de tenant vindos dos parâmetros da requisição * Todo acesso ao banco passa pelo pool de conexões do tenant ativo * O Matcher restringe automaticamente cada consulta ao tenant ativo Esse modelo evita acesso a dados entre tenants e atende requisitos regulatórios e de auditoria. ## Padrões de design *** ### Arquitetura hexagonal Cada contexto delimitado segue o padrão de portas e adaptadores: ``` context/ ├── adapters/ │ ├── http/ │ ├── postgres/ │ └── redis/ ├── ports/ ├── services/ │ ├── command/ │ ├── query/ │ └── worker/ └── domain/ ├── entities/ └── errors/ ``` ### Cqrs-light O Matcher separa os caminhos de escrita e de leitura no nível do serviço: * `*_commands.go` para mutações de estado * `*_queries.go` para operações de leitura Isso melhora a organização do código e permite otimizar os caminhos de consulta de forma independente. ### Padrão outbox O Matcher usa políticas de entrega por evento. O Matcher persiste um registro de outbox para os eventos apoiados em outbox e os despacha de forma assíncrona. Outros eventos podem usar entrega direta com fallback para o outbox quando o circuito está aberto. ## Próximos passos *** Conheça a arquitetura por um exemplo guiado. Revise os mecanismos de autenticação, autorização e isolamento de tenant.