> ## 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 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 as fronteiras claras. Cada módulo pode evoluir de forma independente sem a complexidade de microsserviços. ## Visão geral da arquitetura *** ![Arquitetura do Matcher](https://mintcdn.com/lerian-49cb71fc/8VW3Dv8B_IqwuUob/images/pt/d2/matcher-architecture.svg?fit=max\&auto=format\&n=8VW3Dv8B_IqwuUob\&q=85\&s=5bdf20688102a79e7cfa004e3737a9d6) Visão geral da arquitetura do Matcher ## Contextos delimitados *** O Matcher é dividido em 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, atribuição, resolução) * **Governança**: trilhas de auditoria (logs append-only 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. **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 * Gerenciar conexões com APIs REST e guardar o histórico de schema de cada conexão **Entidades principais:** * `ExtractionRequest`: acompanha um ciclo de vida de extração rodado pelo motor embutido > [!NOTE] > > Veja [Discovery](https://docs.lerian.studio/pt/products/matcher/integrations/matcher-discovery.md) 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 * 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 * Atribuir exceções ao seu time * Oferecer suporte a substituições, ajustes e disputas manuais * Acompanhar o status de resolução * Receber callbacks de resolução de sistemas externos **Entidades principais:** * `Exception`: uma transação não resolvida ### Governança O contexto delimitado de Governança preserva a rastreabilidade da conciliação. **Responsabilidades:** * Registrar em logs de auditoria append-only as mudanças de configuração e as resoluções de exceções * 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 > [!WARNING] > > Os logs de auditoria são append-only. O arquivamento exporta partições mensais antigas para o armazenamento de objetos e depois as remove do banco de dados. ### 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: **1. Configuração** Você define contextos de conciliação, fontes, mapeamentos de campos e regras pela API. **2. Discovery** 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. **3. 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`. **4. Correspondência** 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 de regras `EXACT` e `TOLERANCE` com confiança de pelo menos 90 em 100 se autoconfirmam. Grupos de regras `FUZZY` e `DATE_LAG` sempre exigem revisão manual. Itens não conciliados viram exceções. **5. Tratamento de exceções** O contexto de Exceção classifica as exceções, e o seu time as atribui e resolve. Sistemas externos podem informar resoluções por callbacks. As atualizações de resolução voltam para o Matcher. **6. Governança** A Governança registra em logs de auditoria append-only as mudanças de configuração e as resoluções de exceções. **7. Relatórios** 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 | | **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 | | **Armazenamento de objetos (compatível com S3)** | Armazenamento de arquivos | Arquivos de exportação, evidências de disputas, documentos na fila de extração, arquivamento de logs de auditoria | ### Arquitetura de banco de dados * **Consistência eventual** para as visões de relatório ### Resolução de tenant O Matcher resolve o tenant assim: * O Matcher nunca aceita identificadores de tenant vindos dos parâmetros da requisição > [!NOTE] > > Para detalhes, veja [Segurança](https://docs.lerian.studio/pt/products/matcher/reference/matcher-security.md). ## Padrões de design *** ### 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 *** > [card] [Início rápido](https://docs.lerian.studio/pt/products/matcher/getting-started/matcher-quick-start.md) > > Conheça a arquitetura por um exemplo guiado. > [card] [Segurança](https://docs.lerian.studio/pt/products/matcher/reference/matcher-security.md) > > Revise os mecanismos de autenticação, autorização e isolamento de tenant. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.