Roy-Wanyoike/fuatilia

Fuatilia (Swahili: to track, to follow up) — AR & Collections platform for Kenya. M-Pesa/Daraja-native, DDD core, ledger-first fund truth. # Fuatilia > *Kufuatilia* (Swahili) — **to keep track of, to follow up on.** **Fuatilia** is an Accounts-Receivable & Collections platform for Kenya: track every shilling a customer owes, reconcile it against M-Pesa money (Daraja) without losing a cent, and follow up with consented, intelligence-driven collections. Sister project to `digital-lending-os` — same Kenyan fintech family, TypeScript end to end. ## Design principles 1. **Ledger-first fund truth** — payments, allocations, refunds, and credit notes are append-only facts; corrections are reversing entries, never edits. 2. **The intelligence layer never owns fund truth** — scoring and recommendations read events; they cannot move money. 3. **Channel input is untrusted** — Daraja callbacks are at-least-once; intake is idempotent by construction (`unique(channel, externalRef)`). 4. **Kenya-native** — M-Pesa/Daraja, eTIMS invoice numbering, DPA 2019 consent, WhatsApp opt-in. ## Repository layout ``` docs/ design docs (context map, model, state machines, events, dictionary, review findings, invariants, build plan) + BACKLOG status board src/domain/shared/ shared kernel: Money (minor units, bigint), ids, domain errors src/domain/receivables/ wave 1 — debt position & lifecycle src/domain/payments/ wave 1 — intake idempotency + reconciliation src/domain/adjustments/ wave 1 — refunds, credit notes, credit balance src/domain/allocation/ wave 2 — the settling funnel src/domain/events/ wave 2 — typed event catalog + envelope ``` ## Quickstart ```bash npm ci npm run typecheck npm test ``` Requires Node ≥ 22. No database, no network — the domain core is pure TypeScript, tested with Vitest, built with `tsc`. ## How we ship - Features land as **pull requests** from `feat/*` branches — never direct to `main`. - A PR merges only when the feature is **done, tested, verified, and working**: local tests green, CI green on Node 22/24, diff reviewed. - Squash-merge only; branches …