> ## 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. # Arquitectura > Explora el monolito modular de Matcher, construido sobre DDD, arquitectura hexagonal y CQRS, con siete contextos delimitados que evolucionan de forma independiente. Matcher es un **monolito modular** con diseño guiado por el dominio (DDD) y arquitectura hexagonal. CQRS separa los comandos (escrituras) de las consultas (lecturas). Esto mantiene simple la operación y conserva límites claros. Cada módulo puede evolucionar de forma independiente sin la complejidad de los microservicios. ## Resumen de la arquitectura *** Matcher Architecture ## Contextos delimitados *** Matcher tiene siete módulos. Cada uno es dueño de sus datos y expone interfaces limpias a los demás. * **Configuración**: qué concilias (contextos, fuentes, mapas de campos, reglas) * **Discovery**: conexiones a fuentes de datos externas, detección de esquemas y orquestación de extracciones con el motor de extracción embebido de Matcher * **Ingesta**: entrada de los datos (parseo, validación, normalización) * **Coincidencia**: el motor (ejecución de reglas, puntuación de confianza) * **Excepción**: manejo de los ítems no conciliados (workflow, enrutamiento, resolución) * **Gobernanza**: registros de auditoría (logs inmutables para cumplimiento) * **Informes**: visibilidad (informes, exportaciones, dashboards) ### Configuración Define **qué** concilias y **cómo**. **Maneja:** * Contextos (qué concilias) * Fuentes (de dónde vienen los datos) * Mapas de campos (traducción de los campos externos) * Reglas (cómo hacer coincidir) **Modelos clave:** * `ReconciliationContext`: el ámbito de la conciliación * `ReconciliationSource`: configuración de la fuente * `FieldMap`: reglas de traducción de campos * `MatchRule`: lógica de coincidencia ### Discovery El contexto delimitado Discovery gestiona la conectividad con fuentes de datos externas, la detección de esquemas y la orquestación de extracciones con el motor de extracción. Discovery se ejecuta dentro de Matcher. No hay un servicio de extracción separado que desplegar. **Responsabilidades:** * Gestionar las conexiones a fuentes de datos externas * Detectar y cachear los esquemas de las fuentes * Ejecutar extracciones en el mismo proceso y entregar los resultados directamente a Ingesta * Seguir los ciclos de vida de las conexiones y de las extracciones **Entidades clave:** * `FetcherConnection`: conexión a una fuente externa gestionada localmente por el motor de extracción * `ExtractionRequest`: sigue el ciclo de vida de una extracción que ejecuta el motor embebido Consulta [Discovery](/es/products/matcher/integrations/matcher-discovery) para ver cómo Discovery se conecta a bases de datos externas con el motor de extracción. ### Ingesta El contexto delimitado Ingesta maneja la entrada y la normalización de los datos. **Responsabilidades:** * Parsear los archivos subidos (CSV, JSON, XML) * Validar los datos entrantes contra los esquemas configurados * Normalizar los datos externos a una representación canónica * Detectar y manejar los registros duplicados * Emitir eventos de dominio cuando termina la ingesta **Entidades clave:** * `IngestionJob`: sigue el ciclo de vida y el estado de la ingesta * `Transaction`: registro canónico normalizado de una transacción **Eventos publicados:** * `ingestion.completed`: indica que los datos están listos para la coincidencia ### Coincidencia El contexto delimitado Coincidencia contiene el motor de conciliación. **Responsabilidades:** * Cargar las reglas aplicables a un contexto de conciliación * Ejecutar las estrategias de coincidencia (exacta, por tolerancia, difusa, por fecha) * Calcular las puntuaciones de confianza * Crear grupos de coincidencia y asignar transacciones * Identificar las transacciones no conciliadas **Entidades clave:** * `MatchRun`: ejecución de un trabajo de coincidencia * `MatchGroup`: grupo de transacciones conciliadas * `MatchItem`: asignación individual de una transacción **Eventos publicados:** * `match_group.confirmed`: un grupo de coincidencia quedó finalizado * `match_group.unmatched`: una coincidencia confirmada antes fue revertida * `transaction.pending_review`: un candidato no automático necesita revisión ### Gestión de excepciones El contexto delimitado Excepción gestiona las transacciones sin resolver. **Responsabilidades:** * Clasificar las excepciones por severidad * Enrutar las excepciones a equipos internos o a sistemas externos * Admitir anulaciones y ajustes manuales * Seguir el estado de resolución y los SLA * Integrarse con herramientas externas de workflow **Entidades clave:** * `Exception`: una transacción sin resolver * `Resolution`: resultado del manejo de una excepción * `RoutingRule`: lógica de enrutamiento y de escalamiento **Integraciones:** * JIRA para el seguimiento de incidencias * ServiceNow para incidentes de la Table API * Webhooks para workflows personalizados El conector de ServiceNow crea incidentes de la Table API después de que lo configuras. Usa un intento de creación porque una solicitud reintentada podría crear un incidente duplicado. ### Gobernanza El contexto delimitado Gobernanza preserva la trazabilidad de la conciliación. **Responsabilidades:** * Registrar en logs de auditoría inmutables los workflows de mutación auditables instrumentados * Proveer un historial de auditoría consultable * Admitir los informes regulatorios y de cumplimiento **Entidades clave:** * `AuditLog`: registro solo por adición de los workflows de mutación auditables instrumentados Los registros de auditoría son solo por adición, por diseño. Nadie puede modificar ni eliminar entradas. Este diseño preserva la integridad para el cumplimiento. ### Informes El contexto delimitado Informes provee visibilidad operativa. **Responsabilidades:** * Generar informes de conciliación * Exponer métricas de dashboard * Exportar los datos de conciliación en varios formatos **Entidades clave:** * `Report`: resumen de la conciliación * `Dashboard`: métricas operativas agregadas * `ExportJob`: ejecución asíncrona de una exportación ## Flujo de datos *** La conciliación sigue un pipeline determinista a través de los contextos delimitados: Defines los contextos de conciliación, las fuentes, los mapeos de campos y las reglas a través de la API. Discovery se conecta a las fuentes externas, detecta sus esquemas y ejecuta extracciones en el mismo proceso con el motor de extracción. Discovery entrega los resultados extraídos directamente a Ingesta. Ingesta parsea, valida, normaliza y deduplica los archivos subidos y los datos que extrae Discovery. Ingesta emite un evento `ingestion.completed`. Coincidencia aplica las reglas a las transacciones elegibles y produce grupos de coincidencia con puntuaciones 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 autoconfirmarse. Los grupos FUZZY y DATE\_LAG siempre requieren revisión manual. Los ítems no conciliados se convierten en excepciones. El contexto Excepción clasifica y enruta las excepciones. La resolución ocurre de forma manual o a través de sistemas externos. Las actualizaciones de resolución vuelven a Matcher. Gobernanza registra en logs de auditoría inmutables los workflows de mutación auditables instrumentados a lo largo del pipeline. Los usuarios acceden a informes y dashboards que muestran el estado de la conciliación, las tasas de coincidencia y la antigüedad de las excepciones. ## Componentes de infraestructura *** Matcher depende de los siguientes servicios de infraestructura: | Componente | Propósito | Uso | | --------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------- | | **PostgreSQL** | Almacén principal de datos | Datos de dominio; los despliegues multi-tenant configurados resuelven un pool para cada tenant | | **Valkey (compatible con Redis)** | Cache y coordinación | Deduplicación, locks, 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 internas de trabajo y manejo de dead-letter | | **Systemplane** | Configuración en tiempo de ejecución | Ajustes con hot reload sin reinicio vía la API de administración `/system/matcher/:key` | ### Arquitectura de la base de datos * **Resolución de pool por tenant** en los despliegues multi-tenant configurados, para separar los datos * **Consistencia fuerte** para el estado de coincidencia y de excepciones * **Consistencia eventual** para las vistas de informes ### Multi-tenancy Matcher aplica un aislamiento estricto entre tenants: * En los despliegues multi-tenant con `AUTH_PROVIDER=plugin-auth`, Matcher toma la identidad del tenant de los claims JWT `tenant_id` o `tenantId` * Los despliegues single-tenant y los que tienen la autenticación deshabilitada usan el tenant predeterminado configurado * Matcher nunca acepta identificadores de tenant desde los parámetros de la solicitud * Todo el acceso a la base de datos pasa por el pool de conexiones del tenant activo * Matcher restringe de forma automática cada consulta al tenant activo Este modelo evita el acceso a datos entre tenants y cubre los requisitos regulatorios y de auditoría. ## Patrones de diseño *** ### Arquitectura hexagonal Cada contexto delimitado sigue el patrón de puertos y adaptadores: ``` context/ ├── adapters/ │ ├── http/ │ ├── postgres/ │ └── redis/ ├── ports/ ├── services/ │ ├── command/ │ ├── query/ │ └── worker/ └── domain/ ├── entities/ └── errors/ ``` ### Cqrs-light Matcher separa los caminos de escritura y de lectura en el nivel del servicio: * `*_commands.go` para las mutaciones de estado * `*_queries.go` para las operaciones de lectura Esto mejora la organización del código y permite optimizar los caminos de consulta de forma independiente. ### Patrón outbox Matcher usa políticas de entrega por evento. Matcher persiste un registro de outbox para los eventos respaldados por outbox y los despacha de forma asíncrona. Otros eventos pueden usar entrega directa con un respaldo en outbox cuando el circuito está abierto. ## Próximos pasos *** Explora la arquitectura con un ejemplo guiado. Revisa los mecanismos de autenticación, autorización y aislamiento entre tenants.