Arquitetura

O Matcher é construído como um monolito modular usando Domain-Driven Design (DDD) e arquitetura hexagonal. CQRS separa comandos (escritas) de consultas (leituras). Isso mantém as operações simples enquanto preserva limites claros. Cada módulo pode evoluir independentemente sem a complexidade de microsserviços.

Visão geral da arquitetura

Arquitetura do Matcher — Visão geral da arquitetura do Matcher

Bounded contexts

O Matcher possui sete módulos. Cada um é dono dos seus dados e expõe interfaces limpas para os outros.

Configuration: O que você está conciliando (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 Fetcher embarcado
Ingestion: Entrada de dados (parsing, validação, normalização)
Matching: O motor (execução de regras, scoring de confiança)
Exception: Tratamento de itens não conciliados (workflow, roteamento, resolução)
Governance: Trilhas de auditoria (logs imutáveis para compliance)
Reporting: Visibilidade (relatórios, exportações, dashboards)

Configuration

Define o que você está conciliando e como. Responsabilidades:

Contextos (o que está sendo conciliado)
Fontes (de onde os dados vêm)
Mapas de campos (tradução de campos externos)
Regras (como fazer o matching)

Modelos principais:

ReconciliationContext: O escopo da conciliação
ReconciliationSource: Configuração da fonte
FieldMap: Regras de tradução de campos
MatchRule: Lógica de matching

Discovery

O bounded context de Discovery gerencia a conectividade com fontes de dados externas, a detecção de schema e a orquestração de extrações com o motor Fetcher embarcado. O Matcher hospeda esse motor no próprio processo; o Fetcher não é um serviço remoto. Responsabilidades:

Gerenciar as conexões com fontes de dados externas
Detectar e cachear os schemas das fontes
Executar extrações no próprio processo e encaminhar os resultados diretamente para a Ingestion
Rastrear os ciclos de vida das conexões e das extrações

Entidades principais:

FetcherConnection: Conexão com uma fonte externa gerenciada localmente pelo motor embarcado
ExtractionRequest: Rastreia o ciclo de vida de uma extração executada pelo motor embarcado

Consulte Discovery para ver como o Discovery se conecta a bancos de dados externos com o motor Fetcher embarcado.

Ingestion

O bounded context de Ingestion lida com a entrada e normalização de dados. Responsabilidades:

Fazer parse de arquivos enviados (CSV, JSON, XML)
Validar dados de entrada contra schemas configurados
Normalizar dados externos para uma representação canônica
Detectar e tratar registros duplicados
Emitir eventos de domínio quando a ingestão é concluída

Entidades principais:

IngestionJob: Rastreia o ciclo de vida e status da ingestão
Transaction: Registro canônico de transação normalizado

Eventos publicados:

ingestion.completed: Indica que os dados estão prontos para matching

Matching

O bounded context de Matching contém o motor de conciliação. Responsabilidades:

Carregar regras aplicáveis para um contexto de conciliação
Executar estratégias de matching (exato, tolerância, fuzzy, baseado em data)
Calcular scores de confiança
Criar grupos de match e alocar transações
Identificar transações não conciliadas

Entidades principais:

MatchRun: Execução de um job de matching
MatchGroup: Grupo de transações conciliadas
MatchItem: Alocação individual de transação

Eventos publicados:

match_group.confirmed: Um grupo de match foi finalizado
match_group.unmatched: Um match previamente confirmado foi revertido
transaction.pending_review: Um candidato não automático precisa de revisão

Exception management

O bounded context de Exception gerencia transações não resolvidas. Responsabilidades:

Classificar exceções por severidade
Rotear exceções para equipes internas ou sistemas externos
Suportar overrides manuais e ajustes
Rastrear status de resolução e 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 rastreamento de issues
ServiceNow para incidentes pela Table API
Webhooks para workflows customizados

O conector do ServiceNow cria incidentes pela Table API quando está configurado. Ele usa uma única tentativa de criação porque repetir a requisição pode criar um incidente duplicado.

Governance

O bounded context de Governance preserva a rastreabilidade da conciliação. Responsabilidades:

Registrar fluxos de mutação auditáveis instrumentados em logs de auditoria imutáveis
Fornecer histórico de auditoria consultável
Suportar relatórios regulatórios e de compliance

Entidades principais:

AuditLog: Registro apenas append dos fluxos de mutação auditáveis instrumentados

Os logs de auditoria são apenas append por design. Entradas não podem ser modificadas ou removidas para preservar a integridade do compliance.

Reporting

O bounded context de Reporting fornece visibilidade operacional. Responsabilidades:

Gerar relatórios de conciliação
Expor métricas de dashboard
Exportar dados de conciliação em múltiplos 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 através dos bounded contexts:

Configuration

Contextos de conciliação, fontes, mapeamentos de campos e regras são definidos através da API.

Discovery

O Discovery se conecta a fontes externas, detecta seus schemas e executa extrações no próprio processo com o motor Fetcher embarcado. Os resultados extraídos são encaminhados diretamente para a Ingestion.

Ingestion

Arquivos enviados e dados extraídos pelo Discovery são parseados, validados, normalizados e deduplicados. Um evento ingestion.completed é emitido.

Matching

Regras de matching são aplicadas às transações elegíveis, produzindo grupos de match com scores 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 ser confirmados automaticamente; grupos FUZZY e DATE_LAG sempre exigem revisão manual. Itens não conciliados se tornam exceções.

Exception handling

Exceções são classificadas, roteadas e resolvidas manualmente ou via sistemas externos. Atualizações de resolução são propagadas de volta ao Matcher.

Governance

Fluxos de mutação auditáveis instrumentados através do pipeline são registrados em logs de auditoria imutáveis.

Reporting

Usuários acessam relatórios e dashboards mostrando status da conciliação, taxas de match e envelhecimento de exceções.

Componentes de infraestrutura

O Matcher depende dos seguintes serviços de infraestrutura:

Componente	Propósito	Uso
PostgreSQL	Armazenamento principal	Dados de domínio; deployments 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 de trabalho internas e tratamento de dead-letter
Systemplane	Configuração em runtime	Alteração de configurações sem reiniciar via API admin `/system/matcher/:key`

Arquitetura de banco de dados

Resolução de pools específicos por tenant em deployments multi-tenant configurados para separação de dados
Consistência forte para estado de matching e exceções
Consistência eventual para views de reporting

Multi-tenancy

O Matcher impõe isolamento estrito de tenants:

Com AUTH_PROVIDER=plugin-auth, a identidade do tenant é extraída dos claims JWT tenant_id ou tenantId
Deployments com workos, single-tenant ou autenticação desabilitada usam o tenant padrão configurado
Identificadores de tenant nunca são aceitos via parâmetros de request
O acesso ao banco de dados é delimitado pelo pool de conexões do tenant ativo
Todas as queries são automaticamente restritas ao tenant ativo

Este modelo previne acesso cruzado de dados entre tenants e suporta requisitos regulatórios e de auditoria.

Padrões de design

Arquitetura hexagonal

Cada bounded context segue o padrão de portas e adaptadores:

context/
├── adapters/
│ ├── http/
│ ├── postgres/
│ └── redis/
├── ports/
├── services/
│ ├── command/
│ ├── query/
│ └── worker/
└── domain/
 ├── entities/
 └── errors/

CQRS-light

Os caminhos de escrita e leitura são separados no nível de 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 otimização independente dos caminhos de consulta.

Padrão outbox

O Matcher usa políticas de entrega por evento. Eventos apoiados por outbox persistem um registro de outbox e são despachados de forma assíncrona; outros eventos podem usar entrega direta com fallback de outbox quando o circuito está aberto.

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Visão geral da arquitetura

Bounded contexts

Configuration

Discovery

Ingestion

Matching

Exception management

Governance

Reporting

Fluxo de dados

Componentes de infraestrutura

Arquitetura de banco de dados

Multi-tenancy

Padrões de design

Arquitetura hexagonal

CQRS-light

Padrão outbox

Próximos passos

Início rápido

Segurança

​Visão geral da arquitetura

​Bounded contexts

​Configuration

​Discovery

​Ingestion

​Matching

​Exception management

​Governance

​Reporting

​Fluxo de dados

​Componentes de infraestrutura

​Arquitetura de banco de dados

​Multi-tenancy

​Padrões de design

​Arquitetura hexagonal

​CQRS-light

​Padrão outbox

​Próximos passos

Início rápido

Segurança

Visão geral da arquitetura

Bounded contexts

Configuration

Discovery

Ingestion

Matching

Exception management

Governance

Reporting

Fluxo de dados

Componentes de infraestrutura

Arquitetura de banco de dados

Multi-tenancy

Padrões de design

Arquitetura hexagonal

CQRS-light

Padrão outbox

Próximos passos