Skip to main content
Matcher is built as a modular monolith using Domain-Driven Design (DDD) and hexagonal architecture. CQRS separates commands (writes) from queries (reads). This keeps operations simple while maintaining clear boundaries. Each module can evolve independently without the complexity of microservices.

​
Architecture overview

Matcher Architecture

​
Bounded contexts

Matcher has six modules. Each owns its data and exposes clean interfaces to the others.
  • Configuration: What you’re reconciling (contexts, sources, field maps, rules)
  • Ingestion: Getting data in (parsing, validation, normalization)
  • Matching: The engine (rule execution, confidence scoring)
  • Exception: Handling unmatched items (workflow, routing, resolution)
  • Governance: Audit trails (immutable logs for compliance)
  • Reporting: Visibility (reports, exports, dashboards)

​
Configuration

Defines what you’re reconciling and how. Handles:
  • Contexts (what’s being reconciled)
  • Sources (where data comes from)
  • Field maps (translating external fields)
  • Rules (how to match)
Key models:
  • ReconciliationContext: The reconciliation scope
  • ReconciliationSource: Source configuration
  • FieldMap: Field translation rules
  • MatchRule: Matching logic

​
Ingestion

The Ingestion bounded context handles data intake and normalization. Responsibilities:
  • Parse uploaded files (CSV, JSON, XML)
  • Validate incoming data against configured schemas
  • Normalize external data into a canonical representation
  • Detect and handle duplicate records
  • Emit domain events when ingestion completes
Key entities:
  • IngestionJob: Tracks ingestion lifecycle and status
  • RawImport: Original uploaded payload
  • CanonicalTransaction: Normalized transaction record
Events published:
  • IngestionCompleted: Indicates data readiness for matching

​
Matching

The Matching bounded context contains the reconciliation engine. Responsibilities:
  • Load applicable rules for a reconciliation context
  • Execute matching strategies (exact, tolerance, date-based)
  • Calculate confidence scores
  • Create match groups and allocate transactions
  • Identify unmatched transactions
Key entities:
  • MatchRun: Execution of a matching job
  • MatchGroup: Group of reconciled transactions
  • MatchItem: Individual transaction allocation
Events published:
  • MatchConfirmed: A match group has been finalized
  • TransactionUnmatched: A transaction could not be reconciled

​
Exception management

The Exception bounded context manages unresolved transactions. Responsibilities:
  • Classify exceptions by severity
  • Route exceptions to internal teams or external systems
  • Support manual overrides and adjustments
  • Track resolution status and SLAs
  • Integrate with external workflow tools
Key entities:
  • Exception: An unresolved transaction
  • Resolution: Outcome of exception handling
  • RoutingRule: Routing and escalation logic
Integrations:
  • JIRA for issue tracking
  • ServiceNow for critical incidents
  • Webhooks for custom workflows

​
Governance

The Governance bounded context preserves reconciliation traceability. Responsibilities:
  • Record all system actions in immutable audit logs
  • Provide queryable audit history
  • Support regulatory and compliance reporting
Key entities:
  • AuditLog: Append-only record of system activity
Audit logs are append-only by design. Entries cannot be modified or removed to preserve compliance integrity.

​
Reporting

The Reporting bounded context provides operational visibility. Responsibilities:
  • Generate reconciliation reports
  • Expose dashboard metrics
  • Export reconciliation data in multiple formats
Key entities:
  • Report: Reconciliation summary
  • Dashboard: Aggregated operational metrics
  • ExportJob: Asynchronous export execution

​
Data flow

Reconciliation follows a deterministic pipeline across bounded contexts:
1

Configuration

Reconciliation contexts, sources, field mappings, and rules are defined through the API.
2

Ingestion

External data is uploaded or fetched. Files are parsed, validated, normalized, and deduplicated. An IngestionCompleted event is emitted.
3

Matching

Matching rules are applied to eligible transactions, producing match groups with confidence scores. High-confidence matches are approved automatically. Unmatched items become exceptions.
4

Exception handling

Exceptions are classified, routed, and resolved either manually or via external systems. Resolution updates are propagated back to Matcher.
5

Governance

All actions across the pipeline are recorded in immutable audit logs.
6

Reporting

Users access reports and dashboards showing reconciliation status, match rates, and exception aging.

​
Infrastructure components

Matcher relies on the following infrastructure services:
ComponentPurposeUsage
PostgreSQLPrimary data storeDomain data with schema-per-tenant isolation
RedisCache and coordinationDeduplication, locks, idempotency keys
RabbitMQMessage brokerAsynchronous communication between contexts

​
Database architecture

  • Schema-per-tenant isolation for strong data separation
  • Strong consistency for matching and exception state
  • Eventual consistency for reporting views

​
Multi-tenancy

Matcher enforces strict tenant isolation:
  • Tenant identity is extracted exclusively from JWT claims
  • Tenant identifiers are never accepted via request parameters
  • Database access is scoped through schema resolution
  • All queries are automatically constrained to the active tenant
This model prevents cross-tenant data access and supports regulatory and audit requirements.

​
Design patterns

​
Hexagonal architecture

Each bounded context follows the ports-and-adapters pattern: 
context/
├── adapters/
│ ├── http/
│ ├── postgres/
│ └── rabbitmq/
├── ports/
├── services/
│ ├── command/
│ └── query/
└── domain/
 ├── entities/
 └── errors/

​
Cqrs-light

Write and read paths are separated at the service level:
  • *_command.go for state mutations
  • *_query.go for read operations
This improves code organization and allows independent optimization of query paths.

​
Outbox pattern

Event publication follows the outbox pattern:
  1. Domain state and outbox records are persisted atomically
  2. Background workers publish events to RabbitMQ
  3. Events are marked as processed after successful delivery
This guarantees event delivery even during transient broker failures.

​
Next steps

Quick start

Explore the architecture through a guided example.

Security

Review authentication, authorization, and tenant isolation mechanisms.