WDF National Operations Platform
ARCH-v1.0 · June 2025
Architecture & Infrastructure Blueprint

One machine.
National scale.

A multi-programme operations platform with automated infrastructure orchestration — built to manage WDF's full rollout across SMEs, churches, NPOs, ESD, and pre-schools at province, region, ward, and church level.

8
Workflow Stages
3
Operating Layers
6
Role Levels
∞
Church Subdomains
● Process Engine
Multi-tenant
Auto-provisioning
Cover-gated funding
RLS security
AI website generation
VoIP provisioning
National dashboard

Platform layers

Three stacked layers. Users only see Layer 1. The workflow engine is what drives everything. The infra orchestrator fires silently on every stage transition.

Layer 1
Management Platform
National Admin Dashboard
Provincial Dashboard
Regional LO Dashboard
Community LO Dashboard
Church Leader Portal
Finance Portal
Verifier Portal
Church Management Subsystem
Layer 2
Workflow Engine
Stage Manager (8 stages)
Task Queue (BullMQ)
SLA Timers & Countdowns
Gate Rules Engine
Notification Dispatcher
Evidence & Audit Logger
Role-based Data Filter (RLS)
Reporting Aggregator
Layer 3
Infrastructure Orchestrator
Subdomain Provisioner (Cloudflare API)
Church System Deployer (K8s namespace)
SSL Auto-cert (cert-manager)
Website Generator (Claude API)
Static Site Deployer (Cloudflare Pages)
Email Provisioner (Zoho API)
VoIP Number Provisioner (Euphoria API)
Storage Bucket Creator (S3)
Layer 4
Data & Security
PostgreSQL + Row Level Security
Keycloak (Auth & Roles)
S3 Document Storage
Redis (Cache & Queue)
Audit Log Table (immutable)
Backup Pipeline (pg_dump → S3)
Encryption at rest

8 workflow stages

Every stage has features, rules, and underlying orchestrations. Stage transitions are automated — the engine moves the church forward, not a person.

STAGE 01
🏛️

Application & Onboarding

Triggered by: Completed application form submission
Multi-programme application form (SME / Church / NPO / Pre-school / ESD)
Document upload: ID, proof of address, org docs
Applicant profile created (org + people records)
Province / Region / Ward auto-assigned from address
Officer auto-assigned based on ward coverage
Application status dashboard for applicant
Orchestrations fired
DB record created Officer notification WhatsApp confirmation R350 payment link generated No external API
STAGE 02
💳

R350 ACPN Payment

Triggered by: Payment webhook from gateway
Payment link sent via WhatsApp + email
Instant EFT or card payment (Peach Payments)
Webhook receives confirmation → verifies → marks paid
PDF receipt auto-generated and sent
14-day R3,500 countdown timer starts
Phase 1 task queue created and assigned
Failed payment: retry flow + officer alert after 48h
Orchestrations fired
Peach Payments API Receipt generator SLA timer (14 days) Phase 1 task queue WhatsApp (manual fallback)
STAGE 03
📋

Registration & Compliance

Triggered by: R350 payment verified
NPC name reservation workflow
CIPC document preparation (pre-fill from applicant data)
NPO / PBO / NPC application tracker with status
SARS, UIF, COIDA tracking with expiry alerts
Document checklist per registration type
Officer submits to CIPC — system tracks reference & status
Certificate upload + verification on receipt
Orchestrations fired
CIPC: Workflow-assisted (no public API — officer submits, system tracks) NPO Directorate: manual upload flow Expiry reminder jobs scheduled RPA option later (Playwright)
STAGE 04
💰

R3,500 WDF Membership

Triggered by: R350 verified + within 14-day window
Payment link pushed (same Peach Payments flow)
14-day countdown shown on church + officer dashboards
Reminder at day 7, day 12, day 13
On payment: Phase 2 task queue unlocked
Exception flow: officer can request extension with reason
Finance dashboard shows total membership revenue
Orchestrations fired
Peach Payments API Countdown cron jobs Phase 2 queue unlock Provisioning engine start signal
STAGE 05
⚡

Provisioning Engine

Triggered by: R3,500 payment verified
Subdomain created: gracechurch.wdfnetwork.co.za
K8s namespace provisioned for church management system
SSL certificate auto-issued (cert-manager + Let's Encrypt)
Claude API generates church website from onboarding data
Static site deployed to Cloudflare Pages (free tier)
Email accounts created: pastor@gracechurch.wdfnetwork.co.za
VoIP landline number provisioned (Euphoria Telecom API)
S3 bucket scoped to church for document storage
Church notified with all credentials via secure link
Orchestrations fired
Cloudflare API (subdomain) K8s API (namespace deploy) cert-manager (SSL) Claude API (website gen) Cloudflare Pages API (deploy) Zoho Mail API (email) Euphoria Telecom API (VoIP) AWS S3 (storage bucket)
STAGE 06
👥

Member & Data Capture

Triggered by: Church system provisioned and live
Church management subsystem now active on subdomain
Member capture: full name, ID, phone, household, role
Household capture: address, size, income band, needs
Bursary candidate tagging per member
Attendance tracking for education classes
Data flows back to national platform via API
LO dashboards update in real time as data comes in
Orchestrations fired
Church subsystem → main DB sync Hierarchy rollup (ward→region→province) Dashboard live update (websocket) Offline-first capture (PWA)
STAGE 07
🛡️

Cover & Eligibility

Triggered by: Funding request submitted
Cover check: funeral cover active? Medical/healthcare active?
WDF partner products: Monarch Finance, Sacred Life, Episodic Health
External cover: officer uploads proof → verifier approves
Hard gate: funding approval cannot proceed without verified cover
Cover status per member visible on church + LO dashboards
Cover expiry alerts automated (30 days, 7 days, expired)
Product subscription status pulled or manually confirmed
Orchestrations fired
Monarch Finance: manual confirmation (no public API yet) Sacred Life: manual upload flow Episodic Health: manual upload flow Funding gate BLOCKED if cover unverified Expiry cron jobs
STAGE 08
🚀

Support Release & Reporting

Triggered by: Cover verified + milestones met + verifier approved
Stipend release: linked to milestone evidence (education class running)
Bursary approval: candidate verified, funding source confirmed
Clinic setup milestone tracking + proof upload
Equipment & renovation request flow with evidence
Funder reporting export (PDF + Excel)
National dashboard: member → church → ward → region → province
Audit trail on every release decision (who, when, what evidence)
Province performance scorecards for provincial leaders
Orchestrations fired
Milestone verifier flow Finance approval workflow Report generator (PDF/XLSX) Audit log write (immutable) Dashboard aggregation

Dashboard overview

How the platform looks. Role-based views — same system, different lenses. Data is enforced at DB level via Row Level Security, not just frontend filtering.

Overview
Applications
Churches
Members
Payments
Reports
Infrastructure
Provincial Leader · Gauteng
Navigation
◈  Province Overview
◫  My Regions
⛪  Churches
👥  Members
Operations
📋  Applications
💳  Payments
✅  Milestones
🛡️  Cover Status
Reports
📊  Performance
📎  Evidence
🔍  Audit Log
247
Churches — Gauteng
↑ 18 this month
R864,500
Membership Revenue
↑ R63,000 this month
4,210
Members Captured
↑ 340 this week
31
Pending Cover Check
⚠ funding blocked
Church onboarding by stage — Gauteng
Last 30 days
Stage pipeline
System alerts
⚠ 14 churches approaching 14-day R3,500 window
⛔ 5 churches: R3,500 window expired — escalate
✓ 3 church systems provisioned today
⚠ 2 CIPC registrations overdue for follow-up

Role access matrix

Enforced at DB level via PostgreSQL Row Level Security. Not frontend filtering — actual data isolation. Each role is a Keycloak realm role.

🏛️
National Admin
Scope: All provinces, all data
Full national dashboard
All province performance
All payments & revenue
All audit logs
Infrastructure status
System configuration
All reports & exports
🗺️
Provincial Leader
Scope: Their province only
Province performance dashboard
All regions in their province
Church pipeline by region
Member & household counts
Payment totals (no individual)
Other provinces
System config
📍
Regional LO
Scope: Their region only
Regional dashboard
Their community LOs
Church onboarding status
Milestone tracking
Payment status (not amounts)
Other regions
Infrastructure controls
🏘️
Community LO
Scope: Their ward/churches
Ward dashboard
Their assigned churches
Member capture support
Task checklist (Phase 1 & 2)
Upload evidence
Other wards
Finance data
⛪
Church Leader
Scope: Their church only
Their church profile
Stage progress tracker
Member management
Bursary applications
Payment receipts
Other churches
LO performance data
✅
Verifier / Finance
Scope: Assigned records only
Evidence review queue
Approve / reject milestones
Cover verification
Payment reconciliation
Stipend approval
System configuration
Infrastructure

Third-party integrations

Only confirmed real integrations. Where no API exists, the fastest viable alternative is shown. No guesswork.

💳
Payments
SA-native payment rails
Peach Payments API
Full REST API. Handles card, instant EFT, Apple Pay. Webhook for payment confirmation. Preferred for SA market — used by major SA enterprises.
~1.8–2.5% per transaction
Ozow API
Instant EFT only. REST API with webhook. Fallback option or alternative for churches preferring direct bank EFT.
~1.5% per transaction
📞
VoIP / Landline
Instant number provisioning
Euphoria Telecom API
SA-based VoIP provider with REST API. Can provision numbers programmatically. Numbers route to mobile via SIP or call forward. Best SA option for this use case.
~R50–R100/month per number
Vox Telecom API
Alternative SA VoIP with API access. Larger enterprise footprint. Fallback if Euphoria capacity is insufficient at scale.
~R80–R150/month per number
📧
Email Provisioning
Automated mailbox creation
Zoho Mail API
REST API supports programmatic account creation under a domain. Create pastor@church.wdfnetwork.co.za instantly on provisioning trigger. Free tier up to 5 users per org.
Free–R30/user/month
Google Workspace API
Admin SDK allows programmatic user creation. More expensive but higher trust. Option if WDF wants Google-native mail for churches.
~R75/user/month
🌐
DNS & Hosting
Subdomain + static site delivery
Cloudflare API API
Full REST API for DNS record creation. Wildcard *.wdfnetwork.co.za + per-church CNAME created programmatically in seconds. Cloudflare Pages for static church site hosting.
Free DNS / Pages free tier
ZACR / co.za Registry Manual
No direct public API. Registrar resellers (like Afrihost, Domains.co.za) have portal APIs but not standardised. Recommended: use subdomains of wdfnetwork.co.za only — avoids domain purchase complexity entirely.
Subdomain = R0 cost
📋
Compliance & Registration
CIPC, NPO, SARS tracking
CIPC Workflow-assisted
No public API available. System pre-fills all forms from applicant data. Officer submits manually on CIPC portal. System tracks reference number + status via officer updates. RPA (Playwright) viable later.
CIPC fees: ~R175 NPC registration
CompanyXpress / LexisNexis API
Third-party CIPC resellers with APIs. Can handle NPC name reservation and status lookups. Evaluate for Stage 3 automation upgrade path.
Subscription-based
💬
Messaging & Comms
WhatsApp + notifications
Twilio WhatsApp Business API
WhatsApp Business API via Twilio. Send payment links, stage updates, reminders, credentials. Template messages for transactional use. Well-established SA support.
~$0.005 per message
SendGrid (Email) API
Transactional email for receipts, reports, system notifications. REST API. Free tier: 100 emails/day.
Free → ~$20/month
🤖
AI Layer
Website gen, docs, extraction
Claude API (Anthropic) API
Website content + layout generation from church onboarding data. Document drafting. Data extraction from uploaded compliance docs. Future: intelligent stage suggestions.
~$3–15 per million tokens
🏥
Cover Products
WDF partner products
Monarch Finance Manual upload
No confirmed public API. Member uploads proof of cover. Verifier reviews and approves on system. Cover status stored and tracked. API integration upgradeable when available.
Partner arrangement
Sacred Life / Episodic Health Manual upload
Same approach as Monarch. Officer or member uploads active policy proof. System marks cover verified. Expiry tracked with auto-alerts.
Partner arrangement
🔐
Auth & Security
Enterprise identity management
Keycloak Self-hosted
Open-source enterprise identity provider. Manages all roles, tokens, sessions. Self-hosted — WDF owns all auth data. SAML + OIDC support. K8s deployable.
Free (self-hosted)

Technology stack

Senior-level choices. Every pick justified by scale, SA-market fit, or operational cost. No newcomers.

Infrastructure
Hetzner Cloud (VPS)
Primary compute. German-engineering reliability, 4–5× cheaper than AWS EC2 for equivalent specs.
→ SA latency acceptable. Cost at scale is major factor.
K3s (Kubernetes)
Lightweight K8s. Runs on Hetzner. Manages church namespaces, auto-scaling, rollouts, cert-manager.
→ Church system = K8s namespace, not VM. 1000 churches, 1 cluster.
Cloudflare
DNS, CDN, DDoS protection, static site hosting (Pages), Workers for edge logic.
→ Free tier covers most of WDF's DNS + hosting needs.
AWS S3
Document storage. Per-church scoped buckets. Compliance docs, evidence, receipts, media.
→ MinIO (self-hosted) viable alternative for cost control.
Backend
Node.js + Fastify
Main API server. Fastify over Express — 3× faster, better TypeScript support, plugin architecture fits modular stage design.
→ Handles webhook processing, stage transitions, auth middleware.
BullMQ + Redis
Job queue for async orchestration. Provisioning jobs, cron timers (14-day window, expiry alerts), report generation.
→ Every infrastructure action fires as a job, not a blocking request.
PostgreSQL 16
Primary database. Row Level Security for role-scoped data access. JSONB for flexible milestone/evidence schemas.
→ RLS is the security backbone. Not optional.
Prisma ORM
Type-safe DB client. Schema migrations. Works well with PostgreSQL + TypeScript stack.
→ Keeps DB schema versioned and reviewable.
Frontend
Next.js 14 (App Router)
Admin platform + all dashboards. Server components for data-heavy views. Static export for church sites.
→ SSR for performance, RSC reduces client bundle size significantly.
Tailwind CSS
Utility-first styling. Fast iteration. Dark-mode native. Consistent design tokens across all dashboard views.
→ No design system debt. Ship fast, look professional.
Flutter Web
Church management subsystem (mobile-first, offline-capable). Member capture works in the field without internet.
→ Matches your Flutter expertise. Offline-first is critical for SA field conditions.
Recharts / D3
Dashboard charting. Province performance, member growth, payment pipeline, stage distribution.
→ Recharts for standard charts, D3 for hierarchy (province→ward drilldown).
DevOps & Auth
Keycloak
Auth server. All 6 role levels. JWT tokens. OIDC. Realm per environment. Self-hosted — WDF owns auth data.
→ Enterprise-grade. No vendor lock-in. Scales to thousands of users.
GitHub Actions
CI/CD pipeline. Build → test → deploy to K3s. Church site generation pipeline. Infra-as-code (Terraform) runs here.
→ Free for public repos, cheap for private. Tight GitHub integration.
Terraform
Infrastructure as code. Hetzner servers, Cloudflare DNS zones, S3 buckets all declaratively managed.
→ Reproducible infra. Every env (dev/staging/prod) is code.
Grafana + Loki
Platform observability. Logs from all services. Alerts for failed provisioning jobs, payment webhook failures, SLA breaches.
→ Self-hosted on K3s. Free. WDF sees system health in real time.

Cost estimates

Running costs at initial scale (~500 churches). All figures ZAR approximate. Exchange rate sensitive for USD-priced services.

Service Provider Model Est. Monthly Cost Notes
── INFRASTRUCTURE ──────────────────────
Primary VPS cluster
 Hetzner Cloud 3× CX31 nodes (K3s) ~R1,800/mo Scales horizontally as churches grow
DNS + CDN + Static hosting
 Cloudflare Pro plan ~R400/mo Covers all subdomains + church sites
Document storage
 AWS S3 ~500GB + egress ~R300/mo MinIO self-hosted = R0 (just storage cost)
── PAYMENTS ──────────────────────────────
Payment processing
 Peach Payments 2% per transaction Variable R350 = ~R7 fee. R3,500 = ~R70 fee per church
── COMMUNICATIONS ───────────────────────
WhatsApp notifications
 Twilio Per message ~R300/mo Est. ~5 msgs/church onboarding = 2,500 msgs
Transactional email
 SendGrid Essentials plan ~R200/mo Receipts, reports, system alerts
── PROVISIONING (PER CHURCH) ────────────
VoIP number per church
 Euphoria Telecom Per number ~R75/church/mo 500 churches = R37,500/mo — pass to church membership
Email (Zoho)
 Zoho Mail Per user ~R30/church/mo Or free if ≤5 mailboxes under org plan
── AI ────────────────────────────────────
Website generation
 Claude API Per generation ~R5–15/church One-time cost per church onboarded
── AUTH & OBSERVABILITY ─────────────────
Keycloak + Grafana
 Self-hosted on K3s Part of cluster R0 additional No extra cost — runs on existing cluster

Infrastructure orchestration

What fires automatically when a church crosses each stage gate. This is the machine under the machine.

⚡ Stage 2 → R350 Verified
BullMQ job enqueued
Async job: generate receipt PDF + send via SendGrid + WhatsApp
14-day cron scheduled
Redis TTL-based countdown. Fires reminders at day 7, 12, 13. Escalation at day 14.
Phase 1 task queue created
Tasks assigned to Community LO. Dashboard updated. Officer notified.
🚀 Stage 5 → R3,500 Verified
Cloudflare DNS → CNAME created
gracechurch.wdfnetwork.co.za pointing to K3s ingress. Live in seconds.
K8s namespace provisioned
Church management system deployed as K8s workload. Isolated per church. Shared cluster.
cert-manager issues SSL
Let's Encrypt cert auto-issued for subdomain. HTTPS from day one.
Claude API → website generated
Church name, location, pastor, services fed to Claude. HTML site returned. Deployed to Cloudflare Pages.
Zoho API → email created
pastor@gracechurch.wdfnetwork.co.za created. Credentials sent via secure link.
Euphoria API → number provisioned
Local landline number assigned. Routes to pastor's cell via call forward or SIP app.
S3 bucket created
Scoped bucket: wdf-docs-church-{id}. Policy restricts access to church + admin only.
🛡️ Stage 7 → Funding Requested
Cover gate check (automated)
System queries member_cover table. If funeral_cover = null OR medical_cover = null → funding blocked. No manual bypass without audit log entry.
Verifier queue created
If cover proof uploaded → verifier assigned → review task created in their queue.
Expiry monitor scheduled
Cron job monitors cover expiry dates. Alerts at 30 days, 7 days, 0 days. Cover lapses → funding re-blocked automatically.
Audit log write
Every gate check result written to audit_logs (immutable). Who checked, what result, what evidence, timestamp.
Built to run a country.
Not a spreadsheet.

WDF National Operations Platform — process engine + provisioning machine + data ownership layer. Multi-tenant, role-isolated, automated, and auditable at every step. Architecture version 1.0 · For Thursday demo.

PROCESS
+ PROOF
+ PROVISION