Loading…
← Engineering HandbookComing soon
StokvelOS
AI-powered management for South African stokvels, members transact entirely over WhatsApp in their own language, every rand is reconciled from source, and records mirror to a read-only Notion workspace for full transparency.
View the product page- Data model
- 19 tables across 6 modular schema files · region-pinned jnb1
- Stack
- 11 technologies
- Provenance
- real build journals
The problem
~95% of stokvels run on paper; treasurer fraud is rampant and members have zero visibility. One fraud incident can destroy decades-old community trust. StokvelOS makes every rand visible and every transaction append-only, with the money math done by deterministic code, never by an AI.
.jpg&w=3840&q=75)
Architecture
How it’s wired
A container-level view of the real system, the boundaries, the trust edges, and where intelligence and money actually flow.
Members never leave WhatsApp; Claude classifies each message against the stokvel’s constitution. Every confirmed transaction is written immutably and mirrored to a read-only Notion workspace, "paper can be faked, Notion cannot."
.jpg&w=3840&q=75)
By the numbers
19
tables · 6 schema files
20
rules parsed per constitution
5
automated fraud checks
6
languages live (9 designed)
Stack
Next.js 16 (App Router)React 18TypeScriptAnthropic Claude@notionhq/clientSupabase (Postgres + RLS)Upstash RatelimitWhatsApp Business APIPayFastRechartsjsPDF + papaparse
Intelligence
A neutral "record-keeper" on Anthropic Claude Sonnet 4.6 with two-block prompt caching, a shared, cached "stokvel brain" plus a small uncached per-member block. It only classifies intent and language and narrates; it logs from_cache and token counts on every turn for built-in cost observability, and never settles a cent itself.
Data model
19 tables across 6 modular schema files · region-pinned jnb1
- contributions / payouts / loans, each with a UNIQUE receipt_number and recorded_by
- audit_log is append-only by design: its only RLS policy is SELECT-for-admins, so every write goes through the service role
- every financial record dual-writes its notion_page_id; stokvels holds five notion_*_db_id columns
- pending_confirmations (intent + payload + prompt, 10-min expiry) turns a stateless webhook stateful
Key decisions
Why it’s built this way
Architecture Decision Records, the trade-offs made deliberately, in the open.
ADR-01
AI at the edges, a deterministic core
- Context
- Money math must be exact, testable and auditable, not left to a model.
- Decision
- One Claude call parses each stokvel’s free-text constitution into 20 enforceable rules (grace days, penalty rate, co-sign threshold, quorum…) with a SAFE_DEFAULTS fallback; from then on every penalty, loan schedule and suspension is settled in pure TypeScript.
- Consequence
- Deterministic, testable financial logic and flat AI cost, "parse once with AI, enforce forever for free."
ADR-02
Two-block prompt caching with per-message telemetry
- Context
- A large "stokvel brain" is needed on every WhatsApp turn.
- Decision
- A cached ephemeral block shared across members + a small uncached per-member block, via the prompt-caching API, logging from_cache and tokens_used on every message.
- Consequence
- Low per-message cost with cost observability built into the ledger.
ADR-03
Notion as an auto-provisioned transparency layer
- Context
- Fraud thrives where only the admin sees the books.
- Decision
- On payment confirmation, deploy a per-stokvel read-only 5-database Notion workspace (Members → Contributions / Loans / Payouts / Reports via real relations) and dual-write every record’s notion_page_id.
- Consequence
- Members get independent, tamper-evident visibility, "paper can be faked, Notion cannot."
.jpg&w=3840&q=75)
The hard parts, solved
Where the engineering earned its keep
01
Every rand reconciled from source
The ledger never trusts a stored balance: on every contribution it re-derives Σ confirmed contributions − Σ payouts and raises a critical balance_discrepancy alert whenever the derived total diverges from the recorded funds by more than R10 and 1%.
02
Stateful gating over a stateless webhook
pending_confirmations holds intent, payload and prompt between "Paid R500" and "YES" with a 10-minute expiry; YES/NO is parsed multilingually (yebo · ja · eya · haa … / hayibo · nee · aowa · hapana) before any money moves.
03
Neutral, stateful dispute mediation
A ubuntu-framed mediator runs a 7-state machine (open → investigating → awaiting proof → reviewing → resolved | escalated) persisted with the full thread, auto-summarises past 8 turns to control tokens, and escalates to the chairperson only when the records genuinely can’t settle it.
Sourced from StokvelOS, README, MASTER_PROMPT, schema files, webhook routes.
.jpg&w=3840&q=75)
Keep exploring