Ledgerly
Double-entry bookkeeping with reports, reconciliation, and audit-ready history
Ledgerly began as a practical answer to a daily annoyance: double-entry bookkeeping with reports, reconciliation, and audit-ready history. What started as a scratch solution grew into a full product because the problems it solved kept recurring — for me first, and then for everyone who saw it in action.
Money-moving software is where software engineering meets its highest standard: idempotency, auditability, and the absence of subtle bugs are not features here, they are the product. PayConnect-class platforms in this portfolio are built around one core discipline — every mutation is idempotent, every sensitive action is logged, and every failure is a structured error with a stable code a client can react to.
Features
- Idempotency-key middleware on every mutation so retries can never double-charge
- Webhook processing with signature verification, replay protection, and dead-letter queues
- Ledger-grade audit log: every transfer, refund, and rate change recorded with request IDs
- Dashboard with revenue, churn, and MRR computed from indexed aggregations
- TOTP two-factor authentication for every operator account
- Role-scoped access: support, finance, and admin roles with least privilege
Architecture
The API layer is the heart: a consistent error envelope, schema-first validation before any side effect, rate limits keyed by account, and the idempotency middleware guarding every non-idempotent mutation. The webhook pipeline runs through a queue with retries and exponential backoff, and every event is replayable — the platform can rebuild state from its event history, which is both a debugging superpower and a compliance answer.
Key Technology Decisions
| Decision | Choice | Alternative Considered | Why This Won |
|---|---|---|---|
| Payments | Stripe API with webhooks | In-house processor | Battle-tested rails; in-house would be a liability |
| Idempotency | Redis-keyed middleware | Database unique keys | Reads replay cached responses; no duplicate writes possible |
| Ledger model | Event-sourced history | Mutable balance columns | Every balance is derivable; audits answer every question |
| Auth | TOTP + sessions | Password only | Stolen credentials are useless without the second factor |
| Reporting | Indexed aggregations | OLAP warehouse | Interactive dashboards at this scale need no warehouse |
undefined
Real-World Impact
The defining incident came from a misbehaving client: a retry storm replayed a payment request 214 times in ninety seconds. The idempotency middleware answered 213 of those with the cached original response and executed the mutation exactly once. The error log shows the storm; the ledger shows one charge. That single mechanism paid for the entire platform.
Measured Results
- 214 consecutive retries absorbed with exactly 1 execution
- Webhook delivery reliability 99.98% over six months
- Audit queries answered from event history without joins
- P95 payment flow latency under 800ms including provider round-trip
Frequently Asked Questions
How do you guarantee a retry cannot double-charge?
Every mutation accepts an idempotency key. The middleware checks Redis first: a replay returns the cached original response; a fresh key executes once and caches the result. The client's retry storm proved the design: 214 requests, one charge.
Why event-sourced history instead of a mutable ledger?
Because every balance becomes a question the history can answer. Reconciliation, audits, and 'what happened on March 3rd?' are queries over events rather than forensic archaeology. The events are the truth; the balances are projections.
How are webhooks protected from forgery?
Signatures are verified with the provider's secret, events are idempotent by event ID, and processing runs through a queue with replay protection. A forged event fails signature verification; a replayed event returns the cached outcome.
What happens when an upstream payment provider is down?
Mutations fail fast with a stable error code, clients retry with the same idempotency key, and the queue holds webhook deliveries with exponential backoff. When the provider returns, the backlog drains without a single manual step.
Is two-factor authentication really necessary?
On a platform that moves money, yes — it is the difference between a stolen password being an inconvenience and being an incident. TOTP is enforced for every operator, and every MFA verification is itself audit-logged.
Conclusion
Ledgerly is a live demonstration of everything this portfolio preaches: modular architecture, indexed queries, server rendering, and deployment pipelines that make shipping boring. The patterns are public in the blog articles — steal them, adapt them, and build something that outgrows its prototype without collapsing.