Loading…
← HandbookComing soon
StokvelOS
AI-powered management for South African stokvels — members transact entirely over WhatsApp in their own language, every transaction is immutable, and records mirror to a read-only Notion workspace for full transparency.
View the product pageThe 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 immutable.
Architecture
How it’s wired
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."
<300
char WhatsApp replies
9
languages handled
R1,000
co-confirm threshold
~19
tables
Stack
Next.js 16 (App Router)React 18TypeScriptAnthropic Claude@notionhq/clientSupabase (Postgres + RLS + Realtime)UpstashPayFastWhatsAppjsPDF + papaparse
AI
A neutral "record-keeper" persona on Anthropic Claude Sonnet 4.6 with prompt caching — classifies intent and language and replies in under 300 characters.
Data model
~19 tables across modular schema files
- contributions / payouts / loans — each with a UNIQUE receipt_number and recorded_by
- every record stores its notion_page_id (the transparency mirror)
- immutable audit_log (before_state / after_state JSONB)
- fraud_alerts (severity + JSONB evidence) · risk_snapshots
Key decisions
Why it’s built this way
ADR-01
WhatsApp as the primary interface, not the app
- Context
- 90% of rural SA uses WhatsApp and won’t download apps.
- Decision
- Members transact via natural-language WhatsApp commands processed by Claude; the web dashboard is admin-only.
- Consequence
- Near-zero onboarding friction — at the cost of a hard <300-char, stateless command design.
ADR-02
Notion as the transparency layer
- Context
- Fraud thrives where only the admin sees the books.
- Decision
- Auto-deploy a per-stokvel read-only Notion workspace mirroring every transaction.
- Consequence
- Members get independent, tamper-evident visibility — at the cost of dual-write complexity.
ADR-03
Confirmation-gated, receipt-numbered transactions
- Context
- Money and community trust demand non-repudiation.
- Decision
- No transaction without explicit YES/CONFIRM; >R1,000 needs chairperson co-confirmation; every txn gets a unique receipt and an audit entry.
- Consequence
- A strong audit trail, with pending_confirmations state between messages.
The hard parts, solved
Multilingual code-switching record-keeping
Claude detects the member’s language (isiZulu, isiXhosa, Sesotho, Setswana and more) and replies naturally in it — "code-switching like township communities do" — inside a <300-char WhatsApp budget.
Fraud detection as a first-class agent
Automatic flagging of duplicate payments, balance discrepancies and overdue loans into fraud_alerts with immediate chairperson alerts.
Webhook idempotency
Inbound message_id is stored UNIQUE to dedupe redelivered WhatsApp messages.
Sourced from StokvelOS — README, MASTER_PROMPT, schema files, webhook routes.
.jpg&w=3840&q=75)