Back to Portfolio
ReconcileX: Enterprise Financial Reconciliation & ZATCA Tax Compliance Platform with Hybrid Deterministic Architecture
ERP & Enterprise Systems

ReconcileX: Enterprise Financial Reconciliation & ZATCA Tax Compliance Platform with Hybrid Deterministic Architecture

Open Source Package / Self-Hosted GitHub Repository
Python 3.10-3.14 FastAPI Pandas RapidFuzz Bounded Subset-Sum Combinatorics Model Context Protocol (MCP v2.2) ZATCA E-Invoicing EasyOCR & Qwen2.5-VL ERPNext & Odoo JV Exporter Playwright Chart.js
Executive Summary

An enterprise-grade open-source financial reconciliation engine engineered to eliminate manual spreadsheet matching, combining deterministic zero-hallucination arithmetic with agentic reasoning to resolve bundled batch payouts, ZATCA VAT compliance audits, and balanced ERP journal vouchers.

End-to-End Audit & Close
< 3.5s
Complete reconciliation cycle across 50 invoices & bank feed
Deterministic Arithmetic
100%
Zero LLM rounding hallucinations or phantom ledger variances
Automated Tests Passing
22/22
100% pass rate covering extraction, matching, and MCP tools
Chained Forensic Custody
SHA-256
Immutable cryptographic digest for every invoice and audit log

The Financial Reconciliation Dilemma: Why General LLMs Cannot Balance General Ledgers

Corporate accounting teams spend hundreds of tedious hours each month manually matching supplier invoices against banking statements in spreadsheets. This manual workflow introduces severe financial risks, from duplicate supplier disbursements and missed foreign wire fees to delayed cash flow visibility and reconciliation backlogs during month-end closing.

When modern engineering teams attempt to address this friction using general large language models, they immediately encounter two critical architectural pitfalls. The first is mathematical hallucination; autoregressive language models operate on probabilistic token prediction rather than deterministic arithmetic, inevitably producing phantom pennies, miscalculated tax totals, and unbalanced journal vouchers. The second is data privacy; streaming confidential company bank transactions, corporate balances, and supplier tax IDs to third-party cloud APIs violates strict banking regulations, SOC 2 protocols, and regional data protection mandates.

Hybrid Architectural Paradigm: Strict Separation of Arithmetic Certainty and Semantic Reasoning

To eliminate these systemic liabilities, I engineered ReconcileX around a hybrid decoupled architecture that establishes strict boundaries between mathematical verification and linguistic reasoning:

Deterministic Python engines and vectorized computational libraries such as Pandas and RapidFuzz handle 100% of the arithmetic reconciliation, date window comparisons, and combinatorial calculations with absolute mathematical certainty. Language models, whether local vision models running through Ollama or secure cloud endpoints, are strictly quarantined to semantic edge cases such as disambiguating cryptic banking narrations against official vendor master legal entities.

Furthermore, the system adopts an on-premise local-first privacy standard. All invoice parsing, OCR text extractions, bank statement normalization, and audit hash computations execute entirely within the enterprise perimeter, ensuring zero financial records or banking tokens ever leave internal corporate infrastructure.

The 4-Pass Deterministic Matching Pipeline and Bounded Combinatorial Batch Solvers

At the core of ReconcileX lies a multi-pass reconciliation engine designed to address real-world corporate disbursement complexities through four progressive algorithmic layers:

This four-tier pipeline autonomously reconciles more than ninety-five percent of complex corporate transactions within milliseconds, isolating only true edge cases for single-click review inside the interactive dual split-ledger workspace.

Pass 1 executes strict one-to-one matching requiring exact currency amount equality, a tight date settlement horizon of one to three days, and vendor token similarity exceeding eighty percent
Pass 2 applies relaxed fuzzy matching across an extended seven-day clearing window, leveraging token cleaning algorithms to strip banking noise words from counterparty descriptions
Pass 3 resolves complex bundled batch disbursements using a bounded subset-sum solver to detect when a single lump-sum bank wire settles two, three, or four separate supplier invoices in one batch
Pass 4 accounts for intermediary bank wire deductions and exchange variances within a configurable twenty-five dollar delta tolerance, automatically attributing the difference to bank fee expense

Statutory Tax Verification: ZATCA Compliance, Rate Anomaly Flags, and Cryptographic SHA-256 Fingerprinting

Tax authorities across emerging markets, including the Zakat, Tax and Customs Authority in Saudi Arabia (ZATCA) and the Egyptian Tax Authority, enforce stringent electronic invoicing standards where minor rounding errors result in severe financial penalties:

ReconcileX embeds an automated statutory tax auditor that recalculates effective tax percentages directly from invoice line items and compares them against regional statutory rates, such as 15% VAT in Saudi Arabia or 14% VAT in Egypt. The auditor instantly flags missing vendor VAT registration numbers, mathematical rounding anomalies, and uncalculated sales taxes prior to statutory filing deadlines.

To deliver defensible audit evidence for external financial controllers and government regulators, every ingested document receives a SHA-256 cryptographic digest. This hash establishes an immutable digital chain of custody, ensuring that processed evidence cannot be modified or replaced without immediately invalidating the audit trail.

Enterprise ERP General Ledger Integration and Model Context Protocol (MCP v2.2) Tooling

Reconciliation provides genuine enterprise value only when closing records flow seamlessly into the core accounting ledger. ReconcileX bridges this gap through native enterprise integrations:

The built-in journal voucher generator produces balanced double-entry accounting records conforming strictly to the fundamental accounting equation where total debits equal total credits with zero balance delta. The generator debits accounts payable, credits operating cash, and allocates wire fee deductions into dedicated bank charge expense accounts, exporting structured files ready for direct ingestion into ERPNext, Odoo, QuickBooks, and NetSuite.

Additionally, ReconcileX implements a standardized Model Context Protocol server over standard I/O streams. This standard enables AI engineering environments including Google Antigravity, Cursor, and Claude to execute financial ingestion, trigger multi-pass reconciliations, inspect open discrepancies, and export formatted workbooks directly through conversational agent prompts.

Performance Benchmarks: 22 Automated Tests and Sub-3.5-Second Full Pipeline Close

The platform has been rigorously validated on standard developer hardware through extensive automated test suites:

Passed twenty-two automated unit and integration tests with a 100% pass rate across extraction, matching passes, tax auditing, journal voucher generation, and MCP protocols
Extracted and structured one hundred digital PDF invoices in 1.82 seconds and normalized one thousand bank CSV rows in 0.08 seconds
Completed a full end-to-end reconciliation cycle across fifty invoices and bank statement records, generating an executive-ready multi-tab Excel workbook in under 3.5 seconds
Delivered a high-throughput FastAPI web interface featuring split-ledger controls, forensic document drawers, and dark mode ergonomics for month-end close marathons
Released as a fully transparent, open-source platform under the permissive MIT License to empower corporate finance teams and enterprise developers worldwide
Interactive System Studio & Architecture Screens

Click any screen below to inspect in high-resolution with zoom in, zoom out, pan, and full screen controls.

6 Displays

Interested in a similar project?

We can build a tailored solution customized to your business goals.

Contact Me Now