Arquitetura

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

---

​

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

​

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

​

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:

​

Componentes de infraestrutura

---

O Matcher depende dos seguintes serviços de infraestrutura:

​

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

​

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

---