Xkimi Xa Mali

The problem

A family savings group collects a monthly contribution from every member. Done over chat messages and memory, nobody can say with certainty who has paid, what the pool holds, or what happened to a payment that was later reversed. When the money is real, "roughly right" is not good enough.

How it works

Three Next.js applications share one backend: a member portal, an admin dashboard and a public website. The member portal also hosts the REST API (/api/v1, route → service → repository) and the scheduled jobs.

• Ledger — every rand lands in an append-only, double-entry pool ledger in PostgreSQL. The balance is the sum of credits minus debits, and a nightly reconciliation job checks it.
• Payments — an administrator records each transfer or cash payment against the member and the month, with proof of payment. A payment can be reversed but never erased.
• Jobs — 23 durable, retryable Inngest functions: contribution reminders, overdue sweeps, month rollover, ledger reconciliation, financial-anomaly watch, backups and more.
• Members — each member has a live view of their standing, a year-end forecast and on-time rate, group goals with pledges, and an inbox fed by SMS, email and in-app notifications.

Engineering decisions

The repository records its decisions as architecture decision records:

• PostgreSQL on Neon, chosen over Supabase — ACID transactions are non-negotiable for money.
• Inngest over plain cron — jobs that touch money must be durable and retryable.
• Netcash DebiCheck over PayFast — a South African recurring-debit mandate. The debit-order machinery is built and tested but deliberately dormant: a deployment with no collections provider refuses every money operation rather than pretending.
• Encryption at rest — bank and ID numbers are AES-256 encrypted, with a documented key-rotation procedure.

Built to be trusted

• 179 test files across the three apps.
• 55 database migrations, applied by CI.
• Six GitHub workflows: CI, governance, scheduled backups, a backup self-test, restore drills and preview-database clean-up.
• POPIA-aware data requests and erasure, an audit trail, and admin-signed PDF statements.

Where it stands

All three apps are live and the operating model works end to end: members pay, an administrator records it with proof. Development paused at a deliberate point (September 2026) — what the group needs next is a record of real contributions that a collections partner will accept, and only time and real payments produce that.