Arquitectura

Explora el monolito modular de Matcher sobre DDD, arquitectura hexagonal y CQRS, con siete contextos delimitados que evolucionan de forma independiente.

Matcher está construido como un monolito modular usando Diseño Orientado al Dominio (DDD) y arquitectura hexagonal. CQRS separa los comandos (escrituras) de las consultas (lecturas).

Esto mantiene las operaciones simples mientras se preservan límites claros. Cada módulo puede evolucionar independientemente sin la complejidad de los microservicios.

​

Visión general de la arquitectura

---

Descripción general de la arquitectura del Matcher

​

Contextos acotados

---

Matcher tiene siete módulos. Cada uno posee sus datos y expone interfaces limpias hacia los demás.

• Configuración: Qué estás conciliando (contextos, fuentes, mapeos de campos, reglas)
• Descubrimiento: Conexiones a fuentes de datos externas, detección de esquemas y orquestación de extracción con el motor Fetcher integrado
• Ingesta: Obtención de datos (análisis, validación, normalización)
• Conciliación: El motor (ejecución de reglas, puntuación de confianza)
• Excepciones: Manejo de elementos no conciliados (flujo de trabajo, enrutamiento, resolución)
• Gobernanza: Registros de auditoría (logs inmutables para cumplimiento)
• Reportes: Visibilidad (informes, exportaciones, dashboards)

​

Configuración

Define qué estás conciliando y cómo.

Maneja:

• Contextos (qué se está conciliando)
• Fuentes (de dónde vienen los datos)
• Mapeos de campos (traducción de campos externos)
• Reglas (cómo conciliar)

Modelos clave:

• ReconciliationContext: El alcance de la conciliación
• ReconciliationSource: Configuración de la fuente
• FieldMap: Reglas de traducción de campos
• MatchRule: Lógica de conciliación

​

Descubrimiento

El contexto acotado de Descubrimiento gestiona la conectividad con fuentes de datos externas, la detección de esquemas y la orquestación de extracciones con el motor Fetcher integrado. Matcher aloja ese motor en proceso; Fetcher no es un servicio remoto.

Responsabilidades:

• Gestionar las conexiones a fuentes de datos externas
• Detectar y cachear los esquemas de las fuentes
• Ejecutar extracciones en proceso y trasladar los resultados directamente a Ingesta
• Rastrear los ciclos de vida de las conexiones y las extracciones

Entidades clave:

• FetcherConnection: Conexión a una fuente externa gestionada localmente por el motor integrado
• ExtractionRequest: Rastrea el ciclo de vida de una extracción ejecutada por el motor integrado

Consulta Descubrimiento para ver cómo Descubrimiento se conecta a bases de datos externas con el motor Fetcher integrado.

​

Ingesta

El contexto acotado de Ingesta maneja la entrada y normalización de datos.

Responsabilidades:

• Analizar archivos subidos (CSV, JSON, XML)
• Validar datos entrantes contra esquemas configurados
• Normalizar datos externos a una representación canónica
• Detectar y manejar registros duplicados
• Emitir eventos de dominio cuando la ingesta se completa

Entidades clave:

• IngestionJob: Rastrea el ciclo de vida y estado de la ingesta
• Transaction: Registro canónico de transacción normalizado

Eventos publicados:

• ingestion.completed: Indica que los datos están listos para conciliación

​

Conciliación

El contexto acotado de Conciliación contiene el motor de reconciliación.

Responsabilidades:

• Cargar reglas aplicables para un contexto de conciliación
• Ejecutar estrategias de conciliación (exacta, tolerancia, basada en fecha)
• Calcular puntajes de confianza
• Crear grupos de conciliación y asignar transacciones
• Identificar transacciones no conciliadas

Entidades clave:

• MatchRun: Ejecución de un trabajo de conciliación
• MatchGroup: Grupo de transacciones conciliadas
• MatchItem: Asignación individual de transacción

Eventos publicados:

• match_group.confirmed: Un grupo de conciliación ha sido finalizado
• match_group.unmatched: Una conciliación previamente confirmada fue revertida
• transaction.pending_review: Un candidato no automático necesita revisión

​

Gestión de excepciones

El contexto acotado de Excepciones gestiona las transacciones no resueltas.

Responsabilidades:

• Clasificar excepciones por severidad
• Enrutar excepciones a equipos internos o sistemas externos
• Soportar anulaciones manuales y ajustes
• Rastrear estado de resolución y SLAs
• Integrarse con herramientas externas de flujo de trabajo

Entidades clave:

• Exception: Una transacción no resuelta
• Resolution: Resultado del manejo de la excepción
• RoutingRule: Lógica de enrutamiento y escalamiento

Integraciones:

• JIRA para seguimiento de incidencias
• Webhooks para flujos de trabajo personalizados

ServiceNow es un destino de enrutamiento aceptado, pero su conector HTTP no está implementado.

​

Gobernanza

El contexto acotado de Gobernanza preserva la trazabilidad de la conciliación.

Responsabilidades:

• Registrar flujos de mutación auditables instrumentados en logs de auditoría inmutables
• Proporcionar historial de auditoría consultable
• Soportar reportes regulatorios y de cumplimiento

Entidades clave:

• AuditLog: Registro de solo adición de los flujos de mutación auditables instrumentados

Los logs de auditoría son de solo adición por diseño. Las entradas no pueden ser modificadas o eliminadas para preservar la integridad del cumplimiento.

​

Reportes

El contexto acotado de Reportes proporciona visibilidad operacional.

Responsabilidades:

• Generar informes de conciliación
• Exponer métricas de dashboard
• Exportar datos de conciliación en múltiples formatos

Entidades clave:

• Report: Resumen de conciliación
• Dashboard: Métricas operacionales agregadas
• ExportJob: Ejecución de exportación asíncrona

​

Flujo de datos

---

La conciliación sigue un pipeline determinístico a través de los contextos acotados:

1. Configuración

   Los contextos de conciliación, fuentes, mapeos de campos y reglas se definen a través de la API.

2. Descubrimiento

   Descubrimiento se conecta a fuentes externas, detecta sus esquemas y ejecuta extracciones en proceso con el motor Fetcher integrado. Los resultados extraídos se trasladan directamente a Ingesta.

3. Ingesta

   Los archivos subidos y los datos extraídos por Descubrimiento se analizan, validan, normalizan y deduplican. Se emite un evento ingestion.completed.

4. Conciliación

   Las reglas de conciliación se aplican a las transacciones elegibles, produciendo grupos de conciliación con puntajes de confianza en una escala entera de 0 a 100. Los grupos EXACT y TOLERANCE con una confianza de al menos 90 sobre 100 pueden confirmarse automáticamente; los grupos FUZZY y DATE_LAG siempre requieren revisión manual. Los elementos no conciliados se convierten en excepciones.

5. Manejo de excepciones

   Las excepciones se clasifican, enrutan y resuelven ya sea manualmente o a través de sistemas externos. Las actualizaciones de resolución se propagan de vuelta a Matcher.

6. Gobernanza

   Los flujos de mutación auditables instrumentados a lo largo del pipeline se registran en logs de auditoría inmutables.

7. Reportes

   Los usuarios acceden a informes y dashboards que muestran el estado de conciliación, tasas de conciliación y antigüedad de excepciones.

​

Componentes de infraestructura

---

Matcher depende de los siguientes servicios de infraestructura:

Componente	Propósito	Uso
PostgreSQL	Almacén de datos principal	Datos de dominio; los despliegues multi-tenant configurados resuelven un pool para cada tenant
Valkey (compatible con Redis)	Caché y coordinación	Deduplicación, bloqueos, claves de idempotencia
Backbone de streaming	Publicación de eventos de negocio	Eventos de dominio publicados vía lib-streaming
RabbitMQ	Colas de infraestructura	Colas de trabajo internas y manejo de dead-letter
Systemplane	Configuración en runtime	Modificación de configuraciones sin reiniciar vía API admin /system/matcher/:key

​

Arquitectura de base de datos

• Resolución de pools específicos por tenant en despliegues multi-tenant configurados para la separación de datos
• Consistencia fuerte para estado de conciliación y excepciones
• Consistencia eventual para vistas de reportes

​

Multi-tenancy

Matcher aplica estricto aislamiento de tenants:

• Con AUTH_PROVIDER=plugin-auth, la identidad del tenant se extrae de los claims JWT tenant_id o tenantId
• Los despliegues con workos, single-tenant o autenticación deshabilitada usan el tenant predeterminado configurado
• Los identificadores de tenant nunca se aceptan a través de parámetros de solicitud
• El acceso a la base de datos se delimita mediante el pool de conexiones del tenant activo
• Todas las consultas se restringen automáticamente al tenant activo

Este modelo previene el acceso a datos entre tenants y soporta requisitos regulatorios y de auditoría.

​

Patrones de diseño

---

​

Arquitectura hexagonal

Cada contexto acotado sigue el patrón de puertos y adaptadores:

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

​

CQRS-light

Los caminos de escritura y lectura se separan a nivel de servicio:

• *_commands.go para mutaciones de estado
• *_queries.go para operaciones de lectura

Esto mejora la organización del código y permite la optimización independiente de los caminos de consulta.

​

Patrón Outbox

Matcher usa políticas de entrega por evento. Los eventos respaldados por outbox persisten un registro outbox y se despachan de forma asíncrona; otros eventos pueden usar entrega directa con respaldo de outbox cuando el circuito está abierto.

​

Próximos pasos

---

Inicio rápido

Explora la arquitectura a través de un ejemplo guiado.

Seguridad

Revisa los mecanismos de autenticación, autorización y aislamiento de tenants.