LEDGEROPS / FINANCIAL SYSTEMS
LedgerOps
Financial operations infrastructure built for the moments when payments stop being simple.
LedgerOps is a production-style transaction-processing and financial-operations system that connects payment lifecycle management, Provider communication, double-entry Ledgering, Settlement Reconciliation, exception handling, audit, and operational tooling.
It is designed around a harder question than simply accepting a payment: how do you preserve one trustworthy financial history when requests are retried, messages are duplicated, Providers time out, Settlement data arrives later, and Corrections become necessary?
- Role
- System design · Backend engineering · Frontend operations tooling
- Type
- Financial systems simulation
- Status
- Release 0.3
- Core stack
- Java · Spring Boot · PostgreSQL · Kafka · Next.js
FIG 01 / SYSTEM MODEL
One payment. Three versions of truth.
Processing state, financial state, and external evidence evolve independently. LedgerOps keeps them consistent without pretending they are the same thing.
Provider result
becomes evidence before effect.
Payment completion
shares a boundary with Ledger.
Settlement later
confirms or disputes the history.
01 / PAYMENT PROCESSING
What actually happens after a payment request?
A Payment does not move directly from API request to “success.” LedgerOps separates the request, domain decision, Provider interaction, Provider evidence, and financial posting so each stage can fail or retry without corrupting the others.
The external call
does not happen inside the Payment database transaction.
Provider responses
become immutable evidence before affecting Payment state.
Successful completion
and the financial posting share one boundary.
The important boundary is not HTTP. It is financial state: external calls may fail, repeat, or return late; the internal history must still converge on one accepted outcome.
IMMUTABLE ATTEMPTS
Every Provider submission attempt becomes a separate historical record instead of replacing the previous attempt.
DURABLE INTENT
Payment state and the intent to contact the Provider are committed before asynchronous delivery begins.
EVIDENCE BEFORE EFFECT
A Provider result is persisted and verified before it may change Payment or Ledger state.
02 / FAILURE BEHAVIOUR
The interesting part begins when the happy path stops working.
Financial systems cannot treat every infrastructure failure as a business failure. LedgerOps explicitly models duplicate requests, duplicate messages, ambiguous Provider outcomes, and recovery instead of hiding them behind generic retries.
Two requests should not become two payments.
tenantId + idempotencyKey
ONE FINANCIAL EFFECT
Same logical request
returns the same Payment.
Same key + changed content
becomes an idempotency conflict.
03 / FINANCIAL TRUTH
A successful payment is not complete until the books agree.
LedgerOps uses an immutable double-entry Ledger as the financial system of record. Every posting contains equal debit and credit effects for the same currency, and completed history is never edited in place.
SAR 500.00
If the Journal cannot be posted correctly, the Payment cannot become financially completed.
04 / SETTLEMENT & RECONCILIATION
Processing says what should have happened. Settlement says what the Provider believes happened.
Hours or days later, external Settlement data can arrive containing the Provider's financial record. LedgerOps compares that evidence against internal Payment, Provider, and Ledger facts instead of assuming they agree.
INTERNAL FACTS
EXTERNAL SETTLEMENT
provider_ref_7821
SAR 500.00 · SETTLED
A Payment can be operationally successful while later financial evidence disagrees. Reconciliation detects that disagreement rather than silently allowing two histories to diverge.
05 / CORRECTIONS
Financial history is corrected. It is never rewritten.
The original Journal remains part of financial history. An authorised Correction creates another balanced transaction that explicitly compensates for it.
ORIGINAL POSTING
Journal J-4492 · Payment P-1048↓ CASE INVESTIGATION ↓
AUTHORISED CORRECTION
AUTHORISED CORRECTION
Correction C-091 compensates J-4492Append-only financial history preserves both the original posting and the evidence-bound compensating Journal.
06 / OPERATIONS
The backend also has to explain itself to humans.
LedgerOps includes an authenticated operations application for inspecting Payment activity, Provider health, risk reviews, discrepancies, Cases, Reconciliation state, Ledger records, Tenant configuration, and audit evidence.
Swipe horizontally to inspect the interface →
Operations overview — Tenant-scoped Payment volume, outcomes, Provider health, exceptions, and operational work queues.
01 Transaction state · 02 Exception queues · 03 Provider healthSwipe to inspect →
Swipe to inspect →
07 / SYSTEM DESIGN
The architecture follows the financial boundaries.
LedgerOps is deliberately built as a modular system rather than a collection of unrelated services. Modules own their data and communicate through published interfaces or durable messages, while PostgreSQL remains the transactional source of truth.
- Tenancy
- Merchant
- Risk
- Attempts
- Messaging
- Integration
- Evidence
- Recovery
- Settlement
- Reconciliation
- Casework
- Audit
Platform and external boundaries
Each domain owns its data and publishes interfaces or durable events. The Ledger remains the shared financial truth without allowing modules to query one another's tables directly.
Architecture is supporting evidence after the Payment and financial model are understood.
08 / ENGINEERING INVARIANTS
What the system refuses to get wrong.
- 01
One logical request creates one financial effect.
Tenant-scoped idempotency prevents client retries from silently creating another Payment. Message consumers also tolerate repeated delivery without applying the same business effect twice.
- 02
Completed money must balance.
Every Ledger transaction contains debit and credit entries that balance by currency. A Payment cannot reach financial completion independently of its required Ledger posting.
- 03
History stays immutable.
Provider Attempts, financial postings, Settlement evidence, and Corrections are preserved as historical facts. Corrections create compensating records rather than rewriting history.
- 04
Uncertainty remains uncertainty.
Network timeouts and non-final Provider results do not become invented successes or failures. Recovery continues until authoritative evidence establishes a definitive outcome.
- 05
Tenant ownership is part of correctness.
Tenant context is required for Tenant-owned data, and cross-Tenant financial effects are rejected rather than treated as ordinary authorization mistakes.
ENGINEERING DEPTH
Built to keep financial operations accurate and reliable.
CORE ENGINEERING
- Transactional boundaries
- Double-entry Ledger
- Tenant-wide idempotency
- Optimistic concurrency
- Immutable financial history
- Provider recovery semantics
- Transactional outbox / inbox
- Signed Provider contracts
- Settlement Reconciliation
- Controlled Corrections
OPERATIONAL ENGINEERING
- Spring Batch processing
- Keycloak authentication
- Tenant-scoped operations UI
- Audit evidence
- OpenTelemetry tracing
- Prometheus metrics
- Grafana dashboards
- Testcontainers integration testing
- Flyway migrations
- Executable architecture boundaries
TECHNOLOGY
A restrained stack, chosen around the boundaries.
Backend
Java 21 · Spring Boot · Spring Modulith · Spring Data JPA
Data and processing
PostgreSQL · Apache Kafka · Spring Batch · MinIO · Redis
Identity and operations
Keycloak · OpenTelemetry · Prometheus · Grafana
Web and verification
Next.js · React · TypeScript · JUnit · Testcontainers · Flyway · architecture tests
PROJECT SCOPE
Production-style simulation, clearly scoped.
LedgerOps is a production-style financial systems simulation developed to explore backend correctness and financial operations architecture. It uses synthetic data and a separately deployed Provider Simulator. It does not process real funds, store real card credentials, or claim regulatory certification.