Golden Thread Foundation
Every parcel. Every face. Every time.
Every parcel. Every face. Every time.
Golden Thread is a face-verified humanitarian distribution platform for South African NPOs and churches. Staff log in with OTP, then enroll and verify beneficiaries at the handout point. A beneficiary does not need a phone or email address to receive support. Volunteers scan a beneficiary's face, the system confirms their identity via Claude AI vision, checks cooldown eligibility, and logs the parcel handout with GPS, timestamp, and photo proof.
Multimodal vision compares a live camera capture against enrolled photos. Works across all ethnicities. 80%+ confidence threshold.
Beneficiaries with access can view a stamp-card style history. People without phones or email can still be enrolled and served through staff-led face verification.
Configurable minimum days between collections (default 30). Amber warning if too early. Only Pastor/Admin can override with a logged reason.
Each role sees different KPIs, actions, and data — all from live PostgreSQL aggregates. No dummy data.
Staff users choose role and organisation. Beneficiary enrollment captures available details, consent and face record without requiring phone or email.
Consent timestamps, soft delete, encrypted PII fields, right-to-erasure, full audit trail on every action.
Facebook-style feed with NPO reactions (Pray, Amen, Strength, Blessed), threaded comments, and auto-generated distribution reports.
Rule-based inference engine flags override rate spikes, beneficiary churn, POPIA gaps, and volunteer streaks.
Use this sequence when handing the live system to the owner. The UAT page is a support checklist; the first screen stakeholders should see is the main marketing landing page.
Start at https://gta.cleva-ai.co.za/. Show the enterprise marketing page, role onboarding section, risk controls, and CTA buttons.
Sign in with your own email: enter it, press Send sign-in code, then type the 6-digit code emailed to you (valid for 10 minutes). The founder account can preview the Pastor view with the Pastor demo link; other testers see the role we assigned to them.
Open the pastor dashboard and event view. Explain who has been served, who is outstanding, and how the close-out gives leadership a trusted record.
Show a beneficiary record, collection history, POPIA consent and the enrollment/re-onboarding path. Explain clearly that phone and email are optional; consent, available details and face photo are enough for collection verification.
Return to /demo-login, choose Sign in with face, scan the enrolled beneficiary and confirm the beneficiary dashboard opens without email or phone login.
Use Scan & Distribute to demonstrate beneficiary face verification, match result, cooldown check, optional note, and parcel handout logging.
If no match or cooldown appears, explain that staff can retry, re-onboard, or escalate to pastor/admin override with a reason. The system supports human judgement.
Use the role-specific buttons below (they preview each role for the founder account only). Everyone else signs in with their own email and emailed code and sees the role we assigned. Beneficiaries can sign in with face once enrolled.
| Feature | Status | How It Works |
|---|---|---|
| OTP Email Login | Live | Staff and demo account users enter email → receive 6-digit PIN → type into auto-advancing boxes → JWT session |
| Beneficiary Face Login | Live | Beneficiary opens login → Sign in with face → local face descriptor is matched to an enrolled beneficiary → beneficiary session opens |
| Claude AI Face Matching | Live | Camera capture → POST to server → Claude Sonnet 4.5 compares against enrolled photos → JSON result |
| Beneficiary Enrollment | Live | Details where available → face photo → POPIA consent → done. Phone and email are optional. Cross-org dedup check. |
| Optional Collection Stamp Card | Live | Where a beneficiary has account access, they can see collection history. Service does not depend on a phone or email login. |
| Cooldown Enforcement | Live | Configurable days (default 30). Amber warning + admin-only override with reason codes |
| Calendar & Events | Live | Month/list views, colour-coded by type, inline event creation, close event → auto summary |
| Live Distribution Dashboard | Live | Real-time count via Socket.io. Avg confidence, volunteer count, distribution log. |
| Journal Feed | Live | Posts, NPO reactions (Lucide icons), threaded comments, post types, visibility controls |
| World Model Insights | Live | Override rate, churn, POPIA gaps, efficiency drops, volunteer streaks — all from DB |
| 6 Role Dashboards | Live | Each role: different KPIs, actions, permissions. All data from PostgreSQL aggregates. |
| Onboarding Wizard | Live | Staff users: choose type → create org → done. Beneficiaries: staff-led enrollment with optional contact details and face capture. |
| Audit Trail | Live | Every login, enrollment, distribution, override, deletion: user + timestamp + IP + device |
| Donor Portal | Dashboard only | KPIs + donation history. Section 18A PDF generation planned for v1.1. |
| WhatsApp Reminders | Planned v1.1 | Twilio integration. 24h and 2h reminders. Inbound bot: NEXT, HISTORY, HELP. |
| PWA Offline Mode | Planned v1.1 | Service worker + manifest. CacheFirst for models, StaleWhileRevalidate for API. |
Everyone signs in with their own email address and a 6-digit code that is emailed to them. Ask us to add your email with a role first.
| Role | What They See | Login | |
|---|---|---|---|
| Founder Admin | Your own email (we assign the role) | Owner-only platform oversight, all organisations, all users | Open App → |
| Org Admin | Your own email (we assign the role) | KPIs + trend chart + leaderboard + activity log | Open App → |
| Pastor | Your own email (we assign the role) | Today's events, churn alerts, team feed | Open App → |
| Volunteer | Your own email (we assign the role) | Big "Start Scanning" button + my scan stats | Open App → |
| Donor | Your own email (we assign the role) | R17,500 donated + history (zero PII) | Open App → |
| Beneficiary | Your own email (we assign the role) | Optional account-view demo. Real beneficiaries can be served without phone/email login. | Face Login → |
Sign in with your own email and the 6-digit code we email you.
| # | Action | Expected Result | ✓ |
|---|---|---|---|
| 1 | Login with founder admin email | Dashboard loads with "Welcome," followed by your name (or email) | |
| 2 | Inspect 4 KPI cards | Organisations, Beneficiaries, Distributions and Users. Each count matches what is in the system. | |
| 3 | Look at Organisation Rankings | "Hope Community Church" listed with member + beneficiary counts | |
| 4 | Open sidebar → all nav items visible | Dashboard, Beneficiaries, Calendar, Scan, Journal all present |
Sign in with your own email and the 6-digit code we email you.
| # | Action | Expected Result | ✓ |
|---|---|---|---|
| 1 | Login | Org Admin dashboard with 4 KPI cards | |
| 2 | Inspect KPIs | Beneficiaries, This Month (the last 30 days), Total Distributed and Team Members. Each count matches the system. | |
| 3 | Scroll to trend chart | Bar chart showing "Distribution Trend (30 days)". Hover shows counts. | |
| 4 | Volunteer Leaderboard | Volunteers are listed by number of hand-outs, highest first | |
| 5 | Recent Activity | Entries for recent actions (sign-ins, enrolments, hand-outs) with names and timestamps. A brand-new system shows "No recent activity" until people use it. |
| # | Action | Expected Result | ✓ |
|---|---|---|---|
| 1 | Sidebar → Beneficiaries | Everyone enrolled is listed (20 per page) with a green consent badge where consent was recorded | |
| 2 | Search "Grace" | Results filter in real-time | |
| 3 | Tap a beneficiary | Detail page: profile + PII + collection history | |
| 4 | Tap "Enroll" button | 4-step wizard: Details → Face → POPIA → Done | |
| 5 | Complete enrollment with camera | New beneficiary appears in directory with photo |
| # | Action | Expected Result | ✓ |
|---|---|---|---|
| 1 | Sidebar → Calendar | Month grid with colour-coded events | |
| 2 | Create event via "+ Event" button | Form with title, type, date. Event appears in calendar. | |
| 3 | Tap event → detail page | 3 stat cards (distributed, confidence, volunteers) | |
| 4 | Close event | Confirmation → "Closed" badge → auto summary in journal |
Sign in with your own email and the 6-digit code we email you.
| # | Action | Expected Result | ✓ |
|---|---|---|---|
| 1 | Login | Pastor dashboard with 4 KPIs | |
| 2 | Inspect KPIs | Today's Events, Beneficiaries, Month distributions, Churn Alert | |
| 3 | Today's Events section | A card for each event happening today. If there is none, first create a distribution event for today in the Calendar. | |
| 4 | Tap event → "Start Distributing" | Navigates to Scan page |
This tests the complete distribution flow including cooldown and override.
| # | Action | Expected Result | ✓ |
|---|---|---|---|
| 1 | Sidebar → Scan & Distribute | Choose an open distribution event if asked, then the Scan page shows an "Open Camera" button | |
| 2 | Enroll yourself first (Beneficiaries → Enroll → capture your face) | Enrolled with photo saved to database | |
| 3 | Go back to Scan → Open Camera → Capture & Verify | A few seconds of checking, then a GREEN match with your name + confidence | |
| 4 | Tap "Hand Out Parcel" | "Parcel Handed Out" success. GPS (if allowed) and timestamp logged. | |
| 5 | Tap "Scan Next Person" → scan yourself again | AMBER cooldown warning: "Collected 0 days ago" | |
| 6 | Tap "Override (requires reason)" | Reason code dropdown appears | |
| 7 | Select "Emergency: family crisis" → submit | Distribution logged with override reason. Audit trail created. |
| # | Action | Expected Result | ✓ |
|---|---|---|---|
| 1 | Sidebar → Journal | 4 seeded posts, pinned distribution report at top | |
| 2 | Post an update | New post appears at top of feed | |
| 3 | React with "Pray" on a post | Gold highlight, counter increments | |
| 4 | Show Comments → write a comment | Comment appears with name + timestamp |
Sign in with your own email and the 6-digit code we email you.
| # | Action | Expected Result | ✓ |
|---|---|---|---|
| 1 | Login | Volunteer dashboard with 3 KPIs + big gold "Start Scanning" button | |
| 2 | Tap "Start Scanning" | Navigates to Scan page | |
| 3 | Complete a scan + distribute | Full flow works: camera → match → distribute → success |
| # | Action | Expected Result | ✓ |
|---|---|---|---|
| 1 | Open sidebar | Dashboard, Beneficiaries, Scan and Journal visible (no Calendar) | |
| 2 | Beneficiaries → tap any person | Name and available contact details visible. No address or ID number (PII hidden). Phone may be blank for real beneficiaries. | |
| 3 | Check for delete icon | No trash icon — volunteers cannot delete | |
| 4 | Scan → trigger cooldown | Cooldown warning shown but no override button, with the message "Ask a Pastor or Admin to override this cooldown if needed" |
Sign in with your own email and the 6-digit code we email you.
| # | Action | Expected Result | ✓ |
|---|---|---|---|
| 1 | Login | Donor dashboard loads | |
| 2 | Inspect the KPI cards | Total Donated, Lives Impacted, Parcels Delivered and This Month. The total matches the donations recorded for this donor. | |
| 3 | Your Donations section | 3 donations with org name, date, ZAR amount | |
| 4 | Open sidebar | Only Dashboard — no Beneficiaries, Calendar, Scan, Feed |
Real beneficiaries use Sign in with face after enrolment. Staff sign in with their own email and emailed code.
| # | Action | Expected Result | ✓ |
|---|---|---|---|
| 1 | Open /demo-login and choose Sign in with face | Camera opens and shows beneficiary face sign-in flow | |
| 2 | Scan an enrolled beneficiary face | Beneficiary dashboard loads without email or phone login | |
| 3 | Inspect the stamp card | Gold header with name + org. 10-stamp grid. Collected stamps = gold checkmarks. | |
| 4 | Check "Total" badge | Shows total parcels received | |
| 5 | Open sidebar | Only Dashboard — minimal UI, nothing else visible |
| # | Test | Expected | ✓ |
|---|---|---|---|
| 1 | Visit /api/auth/me with no cookie (incognito) | HTTP 401 | |
| 2 | Enter wrong PIN at login | "Wrong code. Please try again." Inputs clear. | |
| 3 | Paste the 6-digit code from your email into the PIN boxes | All 6 digits fill, auto-submits | |
| 4 | Sign out → refresh | Redirected to login. Cookies cleared. |
| # | Test | Expected | ✓ |
|---|---|---|---|
| 1 | Open on phone (375px width) | Bottom tab bar with gold Scan button. KPIs in 2-column grid. | |
| 2 | Tap hamburger menu | Sidebar slides in with backdrop overlay | |
| 3 | Open camera on mobile | Camera fills viewport. Scan ring visible. Capture works. | |
| 4 | Beneficiary stamp card on mobile | Card stacks properly. Stamps are tappable size (44px+). |
| # | Test | Expected | ✓ |
|---|---|---|---|
| 1 | Background colour throughout | Dark #0D0D0D base with #1E1E24 surface cards | |
| 2 | Gold accent used sparingly | Gold = logo, primary KPI, CTA buttons, active nav. Silver/grey = everything else. | |
| 3 | Fonts | Playfair Display = headings. Lato = body. | |
| 4 | No emoji anywhere | Only Lucide icons. Per design spec. | |
| 5 | Touch targets | All buttons at least 44px × 44px |
By signing below, the tester confirms they have completed the relevant test scenarios and noted any issues.