Loading…
AdminOS
A WhatsApp-native, multi-tenant business OS for South African SMEs, the interface is the customer’s existing WhatsApp line, not a dashboard.
View the product page- Data model
- 86 tables · all under RLS · 147 policies · 43 migrations
- Stack
- 14 technologies
- Provenance
- real build journals
The problem
SA has ~3.7M small businesses running on "a WhatsApp group, a cashbook, and a prayer." Existing tools fail them on USD pricing, no local-language support, heavy bundles that die on prepaid data, and onboarding that assumes IT staff.
.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.
The 9-step pipeline detects language with zero-cost keyword matching, resolves intent/sentiment/language in one Promise.all, checks the Redis FAQ cache (zero-token on hit), and only calls Claude on a miss. Vercel Cron fans out to Inngest agent functions for scheduled work.
.jpg&w=3840&q=75)
By the numbers
86
tables · all under RLS
147
RLS policies · 43 migrations
4
AI cost-control layers
7
specialist AI agents
Stack
Next.js 16 (App Router)React 19TypeScriptAnthropic ClaudeSupabase (Postgres + RLS)Upstash RedisInngestResendMeta WhatsApp Cloud API v19PayFast (one-off)Paystack (subscriptions)xlsx · pdf-parse · mammoth (doc ingestion)PostHognext-pwa
Intelligence
Seven named Claude agents, Alex (inbox), Care (wellness) and Pen (email, streamed over SSE) on Sonnet 4.6; Chase (debt), Doc (documents) and Insight (briefs) on Haiku 4.5; plus Langa, an AI business mentor, on Sonnet. Opus 4.8 is reserved for Enterprise strategy. Each agent carries its own token budget, and the exact model IDs are pinned in code.
Data model
86 tables · all under RLS · 147 policies · 43 migrations
- Tenant claims (tenant_id, role, plan) live in service-role-only app_metadata, never user-owned metadata, so current_tenant_id() denies by default
- conversations first-class (intent / sentiment / status at thread level); messages carry the full WhatsApp delivery lifecycle + from_cache + tokens_used
- audit_log is append-only: UPDATE/DELETE revoked at the DB level, even for the service role
- ai_usage_logs, a durable per-call ledger (tokens_in/out, model, cost in ZAR) behind the Redis budget counters
Key decisions
Why it’s built this way
Architecture Decision Records, the trade-offs made deliberately, in the open.
ADR-01
Tenant claims in service-role-only app_metadata
- Context
- If tenant_id lives in user-owned metadata, one self-service updateUser() call could forge another tenant’s identity, POPIA §26 special personal information (payroll, disciplinary, wellness) is at stake.
- Decision
- tenant_id, role and plan live in raw_app_meta_data (service-role-only); current_tenant_id() reads app_metadata alone and returns NULL, deny, when absent, so one function governs ~40 RLS policies.
- Consequence
- An entire class of cross-tenant escalation is closed at the JWT layer, shipped as a copy → deploy → strip migration rollout with zero session blackout.
ADR-02
A four-layer AI cost engine
- Context
- AI is the dominant cost of goods on a low-ARPU SA SME product.
- Decision
- (1) feature→model routing that defaults unknown work to Haiku; (2) two-level prompt caching (a per-tenant system prompt rebuilt only past 24h, sent with Anthropic cache_control: ephemeral); (3) a Redis FAQ cache (7-day TTL, zero-token on hit); (4) per-tenant daily token budgets (25k→2M) under a 50M/day global backstop.
- Consequence
- Every token is routed, cached, metered and rate-limited, margin protected by design, not by hope.
ADR-03
Fail-closed on ceilings, fail-open on outages
- Context
- Metering must protect margin without letting a Redis blip take AI offline for paying businesses.
- Decision
- Only a successful Redis read that shows a cap hit blocks a call; a Redis error returns allowed + degraded. An abuse tripwire (>50% of a plan’s daily budget in one hour) sets a 24h hard block.
- Consequence
- Safe unit economics that degrade gracefully instead of failing shut.
ADR-04
Meta WhatsApp Cloud API direct, not a BSP
- Context
- Twilio adds p99 4–8s latency in SA and USD billing.
- Decision
- First-party Meta Cloud API v19, HMAC-SHA256 (x-hub-signature-256) with a timing-safe compare, a non-blocking 200-within-5s reply, and a Redis dedup window.
- Consequence
- No BSP cost or dependency; tenants complete their own WABA verification.
.jpg&w=3840&q=75)
The hard parts, solved
Where the engineering earned its keep
01
A 9-step, timeout-guarded workflow engine
Every inbound message runs loadContext → classifyIntent → checkFAQCache → checkPlanLimits → generateResponse → sendWhatsApp → logAudit → updateDashboard → recordWellness, each wrapped in its own timeout (Claude 20s, intent 8s, FAQ 2s) inside Vercel’s 30s. On any failure it substitutes a human-escalation message, writes an audit record and short-circuits, one slow step can’t stall the pipeline.
02
Prompt injection on a public channel
A public WhatsApp number is an open pipe to the LLM. Three separate sanitizers defend it, 17 regex patterns + a 2000-char cap on inbound before any DB store, a stricter 500-char control-char strip on tenant config to stop cross-tenant cache poisoning, and an 80k cap on parsed documents.
03
Persistent AI memory across sessions
Up to three categorized insights (revenue / staff / operations / market) are extracted from each advisor response into a business_insights table, then the last ten are re-injected as "BUSINESS MEMORY" into the next session, genuine long-term continuity, not just per-request context.
Sourced from AdminOS, ARCHITECTURE, SYSTEM_DESIGN, SECURITY_AUDIT_REPORT, WONDERLAND_DECISIONS, supabase/migrations (86 tables).
.jpg&w=3840&q=75)
Keep exploring