Financial Infrastructure

LedgerLens Recon

LedgerLens Recon is a small, production-minded reconciliation CLI built on a simple premise: not every reconciliation problem needs Airflow or Kafka. Many are batch, deterministic, and moderate-volume — better solved with strong correctness and clear reporting than with orchestration overhead. It matches Stripe (API or mock) against an internal database or CSV, scores confidence per match, and outputs a summary Excel report with color-coded rows.

3 weeksSource

The Problem

Teams often reach for heavyweight orchestration frameworks for reconciliation jobs that are actually batch, deterministic, and moderate in volume — adding operational complexity to a problem that mainly needs correctness, idempotency, and a report someone can actually read.

The Solution

Built a modular CLI with a Stripe client (with a mock mode), a SQLAlchemy DB client (with a CSV mock fallback), and a matcher that uses transaction ID as the primary key plus amount and timestamp tolerance for validation — categorizing every record as matched, mismatched, or missing, with a 0.0–1.0 confidence score, then writing it all to a structured Excel report via openpyxl.

Architecture

Modular package layout: data_sources, reconciliation, reporting, utils

Stripe API client with a mock mode for credential-free runs

SQLAlchemy DB client with a CSV mock fallback

Matcher using transaction ID as primary key, with configurable amount and timestamp tolerance

openpyxl-based Excel writer producing a summary sheet plus color-coded status rows

Technologies Used

PythonSQLAlchemyStripe APIopenpyxl

Challenges

1Keeping the tool genuinely simple while still meeting production basics — structured logging, config-driven thresholds, unit tests
2Making the Excel report itself a usable artifact for non-engineers, not just a debug dump

Engineering Trade-offs

1Chose a CLI over a scheduled service or dashboard — matches how batch, moderate-volume reconciliation is actually run day-to-day, at the cost of no built-in scheduling or historical trend view
2Built mock modes for every external dependency instead of requiring live credentials to run — the whole pipeline is testable and demoable with zero setup, at the cost of mocks needing to be kept in sync with real API behavior
3Kept report output deterministic with stable ordering rather than optimizing for write speed — reruns are safely diffable, at the cost of slightly slower report generation on large files

Lessons Learned

1Not every reconciliation problem needs orchestration — clarity and idempotency often matter more than scale
2A well-designed report can be the actual product, with the matching logic underneath it just doing its job quietly

Related Projects

View all

Featured

Financial Infrastructure

TxCore

Financial transaction infrastructure with distributed backend, double-entry accounting, and webhook processing.

View project

Featured

Financial Infrastructure

Sentinel

Open-source trust layer for financial systems where AI agents, services, and humans all act on shared infrastructure — built around an immutable audit ledger and real-time risk intelligence.

View project

Featured

Financial Infrastructure

Data Drift Diagnosis & Reconciliation Service

A production-grade reconciliation engine that matches transactions against bank statements, then statistically detects and diagnoses why match rates have drifted — not just that something broke.

View project

LedgerLens Recon