Saltar al contenido principal
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

Matcher Architecture

​
Contextos acotados

Matcher tiene seis 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)
  • 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

​
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
  • RawImport: Carga original subida
  • CanonicalTransaction: Registro de transacción normalizado
Eventos publicados:
  • IngestionCompleted: 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:
  • MatchConfirmed: Un grupo de conciliación ha sido finalizado
  • TransactionUnmatched: Una transacción no pudo ser conciliada

​
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
  • ServiceNow para incidentes críticos
  • Webhooks para flujos de trabajo personalizados

​
Gobernanza

El contexto acotado de Gobernanza preserva la trazabilidad de la conciliación. Responsabilidades:
  • Registrar todas las acciones del sistema 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 actividad del sistema
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

Ingesta

Los datos externos se suben o se obtienen. Los archivos se analizan, validan, normalizan y deduplican. Se emite un evento IngestionCompleted.
3

Conciliación

Las reglas de conciliación se aplican a las transacciones elegibles, produciendo grupos de conciliación con puntajes de confianza. Las conciliaciones de alta confianza se aprueban automáticamente. Los elementos no conciliados se convierten en excepciones.
4

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.
5

Gobernanza

Todas las acciones a lo largo del pipeline se registran en logs de auditoría inmutables.
6

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:
ComponentePropósitoUso
PostgreSQLAlmacén de datos principalDatos de dominio con aislamiento de esquema por tenant
RedisCaché y coordinaciónDeduplicación, bloqueos, claves de idempotencia
RabbitMQBroker de mensajesComunicación asíncrona entre contextos

​
Arquitectura de base de datos

  • Aislamiento de esquema por tenant para fuerte 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:
  • La identidad del tenant se extrae exclusivamente de los claims del JWT
  • Los identificadores de tenant nunca se aceptan a través de parámetros de solicitud
  • El acceso a la base de datos se limita a través de la resolución de esquemas
  • 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/
│ └── rabbitmq/
├── ports/
├── services/
│ ├── command/
│ └── query/
└── domain/
 ├── entities/
 └── errors/

​
CQRS-light

Los caminos de escritura y lectura se separan a nivel de servicio:
  • *_command.go para mutaciones de estado
  • *_query.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

La publicación de eventos sigue el patrón outbox:
  1. El estado de dominio y los registros outbox se persisten atómicamente
  2. Workers en segundo plano publican eventos a RabbitMQ
  3. Los eventos se marcan como procesados después de la entrega exitosa
Esto garantiza la entrega de eventos incluso durante fallas transitorias del broker.

​
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.