Helpers Community

A community mutual-aid platform with P2P Help Circles, AI risk heuristics, and a full admin console. Members Give Help (pledges) and Receive Help (withdrawals) backed by an in-app reserve and a 14-section admin portal for platform operations.

The platform is engineered to outlast the structural failure that took down 2010s MMM-style schemes: every cent of member growth is backed by a real transaction row, solvency is auto-throttled at the data layer, and admin balances are auditable. See worklog.md for the task history.

Tech stack

Layer	Choice
Framework	Next.js 16 (App Router) + React 19
Language	TypeScript (strict)
ORM	Prisma 6
Database	MySQL 8 (production), SQLite supported in dev
Auth	bcrypt + JWT (httpOnly) + TOTP 2FA
AI	z-ai-web-dev-sdk for the member chatbot, heuristic engine for admin insights
Styling	Tailwind CSS + shadcn/ui
Deploy	output: "standalone" (Node 22 / Caddy / Docker)

Member features

• Give Help — pledge to the community pool, choose a help plan, see live growth
• Receive Help — request a payout (with 7-day cooling period, daily cap, KYC)
• P2P matching — automated pledge ↔ withdrawal matching, proof upload, OCR verify
• Vault — live solvency tracker + 30-day growth timeline
• Ledger — public audit trail with hash verification
• Help Circles — private group savings (1–20 members, invite code)
• Daily check-in — streak reward capped at 0.5% of balance
• Bank accounts — verified via small test-deposit challenge
• Notifications — in-app + email digest
• AI support chatbot — Z-AI LLM with rule-based fallback

Admin features (14 sections)

• Dashboard — inflow/outflow, reserve health, dispute queue, KYC queue
• Members — directory, search, filter, per-member detail drawer with all admin actions
• Help Plans — configurable product catalog (growth rate, term, limits, intake cap, referral depth)
• Deposits — list, status change, force-mature, growth-rate override
• Payouts — withdrawal queue processing, complete, reject, refund
• P2P Matches — list, cancel, refund pledge capacity
• Disputes — resolve in favor of user / platform
• KYC Queue — approve / reject with tier auto-bump
• Anti-Abuse — multi-account detection, ban / unban
• Moderation — forum / gratitude / check-ins / circles / broadcasts
• AI Insights — heuristic fraud, matching, reserve, growth, LLM probe
• Admin Roles — create / edit / delete admin accounts with permission gating
• Settings — solvency thresholds, branding, environment, insurance, security
• Audit Log — every admin action captured with before/after delta

Anti-MMM safety rails (server-enforced)

• referralDepth capped at 2 — no multi-level MLM
• dailyIntakeCap per plan — no blow-up day
• solvency gate on plan publish — rejects plans whose projected payout > 5× reserve
• dailyWithdrawalCap per member — ₦500k/day
• 7-day cooling period between first pledge and first withdrawal
• pledgeFreezeActive / withdrawalsFrozen / unwindMode — admin-controlled, audit-logged
• auto-sunset cron — plans with archivedAt past automatically stop accepting pledges
• matchedAmount rollback on match expiry — giver pledge capacity returns to the pool

Quick start

# 1. Install
npm install

# 2. Set up the database
cp .env.example .env  # then edit DATABASE_URL
npx prisma migrate deploy
npx prisma generate

# 3. (Optional) Seed demo data
npm run db:seed

# 4. Run
npm run dev
# → http://localhost:3000

Required env vars

DATABASE_URL="mysql://user:pass@localhost:3306/givehelp"
JWT_SECRET="<32+ random chars>"
CRON_SECRET="<32+ random chars>"

Without JWT_SECRET in production, the app refuses to start. Without CRON_SECRET in production, /api/cron-match is locked.

Optional: AI chatbot

cp .z-ai-config.example .z-ai-config
# then fill in your Z-AI baseUrl + apiKey

Scripts

Command	What it does
npm run dev	Dev server (Turbopack)
npm run build	Production build (output: "standalone")
npm start	Run the standalone build
npm run lint	ESLint
npm run db:migrate	Apply Prisma migrations
npm run db:push	Push schema (dev only)
npm run db:seed	Seed demo data (dev only)
npm run db:reset	Drop + recreate + seed

Repository layout

.
├── prisma/                  # Prisma schema + migrations
├── public/                  # Static assets + service worker
├── src/
│   ├── app/                 # Next.js App Router (pages + API)
│   │   ├── api/             # 45+ REST endpoints
│   │   ├── admin/           # Admin portal entry
│   │   └── (other)         # Member-facing pages
│   ├── components/
│   │   ├── admin/           # Admin shell + 14 section components
│   │   ├── community/       # Member dashboard, give/receive, etc.
│   │   └── ui/              # shadcn/ui primitives
│   ├── lib/                 # db, auth, growth, matching, AI engine
│   └── hooks/               # use-toast, use-mobile
├── tests/                   # Runtime / container tests
└── worklog.md               # Chronological task history

Security model

• All admin routes gated by requireAdmin(permission) + TOTP 2FA
• Member mutations gated by getCurrentUser() + feature flags
• Rate limiting on auth + admin-login (10/15min/IP)
• JWT access (7d) + refresh (30d), httpOnly cookies
• Every admin write audited to AdminAction with before/after metadata
• Service worker v2 bypasses /api/* (network-first for HTML, cache-first for hashed assets)
• bcrypt cost 12

License

MIT — see LICENSE.

Contributing

This project is in active development. Read worklog.md first, then open an issue describing the change you want to make before sending a PR.