Waaiio
WhatsApp-first business automation platform. Businesses connect their WhatsApp number and get AI-powered booking, payments, ticketing, ordering, and customer engagement -- all through conversational flows. Live in 5 countries (US, CA, NG, GH, UK) with multi-currency payment processing across 5 gateways.
See CLAUDE.md for golden rules, pre-change checklists, and deep implementation details.
Architecture
| Layer | Stack |
|---|
| Frontend | Next.js 14, React 18, TypeScript, Tailwind CSS |
| Admin Panel | Vite + React 18 (separate app in admin/) |
| Database | Supabase (PostgreSQL + Auth + Storage + Realtime) |
| WhatsApp | Meta Cloud API |
| Payments | Paystack (NG/GH), Stripe (US/GB/CA), Flutterwave, Square, PayPal |
| AI | Anthropic Claude (intent detection + voice transcription) |
| Email | Resend |
| Monitoring | Sentry + PostHog |
| Rate Limiting | Upstash Redis (in-memory fallback when unconfigured) |
| Deploy | Vercel (4 deployments) |
Quick Start
npm install
cp .env.example .env.local # Fill in required values
npm run dev # http://localhost:3000
# Admin panel (separate app)
cd admin && npm install && npm run dev # http://localhost:8083
Project Structure
app/
api/ # ~150 API routes
dashboard/ # Protected business dashboard pages
(auth)/ # Login, signup, forgot-password
(marketing)/ # Public marketing pages
get-started/ # Onboarding wizard
checkin/ # QR check-in pages (property, events)
lib/
bot/ # WhatsApp bot engine
bot.service.ts # Main orchestrator (~2,500 lines)
flows/ # 17+ conversational flows (executor, step-manifest)
handlers/ # 9 handler modules
channels/ # Channel resolution + message sending
payments/ # Gateway integrations (factory pattern)
capabilities/ # 24+ capability types, tier gating
supabase/ # 3 DB clients (browser, SSR, service)
pdf/ # PDF generation (invoices, receipts, tickets, contracts)
email/ # Email templates + sending
components/
dashboard/ # DashboardProvider, Sidebar, OnboardingChecklist
ui/ # Shared UI primitives
admin/ # Separate Vite admin panel
src/pages/ # 43+ admin pages
src/lib/ # Admin utilities
supabase/
migrations/ # 219 migrations (NNN_description.sql)
functions/ # Edge Functions (cron jobs)
Path alias: @/* maps to project root.
Database
- Supabase project ref:
cxcmiqotkowhxinjbytg
- 219 migrations, 100+ tables, RLS on every table in public schema
Three client patterns
| Client | Import | Use case |
|---|
| Browser | createClient() from @/lib/supabase/client | Client components, respects RLS |
| SSR | createClient() from @/lib/supabase/server | Server components, reads cookies |
| Service | createServiceClient() from @/lib/supabase/service | Admin/cron only, bypasses RLS |
Migrations
Named NNN_description.sql. Run on remote via Management API:
SQL=$(cat supabase/migrations/NNN_file.sql)
curl -s -X POST "https://api.supabase.com/v1/projects/cxcmiqotkowhxinjbytg/database/query" \
-H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d "$(jq -n --arg q "$SQL" '{query: $q}')"
Environment Variables
See .env.example for the full list. Categories:
| Category | Examples | Notes |
|---|
| Supabase | NEXT_PUBLIC_SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY | URL and anon key are public; service key is server-only |
| WhatsApp | META_CLOUD_ACCESS_TOKEN, META_APP_SECRET | Never expose META_APP_SECRET to client |
| Payments | STRIPE_SECRET_KEY, PAYSTACK_SECRET_KEY | Secret keys are server-only |
| AI | ANTHROPIC_API_KEY | Server-only |
| Email | RESEND_API_KEY | Server-only |
| Analytics | NEXT_PUBLIC_POSTHOG_KEY | Public (browser-bundled) |
| Rate Limiting | UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN | Optional; falls back to in-memory |
Rule: Never use NEXT_PUBLIC_ or VITE_ prefix for secret keys. They get bundled into browser JS.
Testing
npm run test # 517+ unit tests, Vitest
npm run test:e2e # Playwright smoke tests
npm run certify:local # Full production certification (see below)
Bot-specific testing uses a harness at lib/bot/__tests__/bot-harness.ts with mock sender, mock DB, and conversation fixtures.
Local Production Certification
Run all verification stages in order — lint, tests, builds, database, Playwright:
npm run certify:local # Full run
npm run certify:local -- --skip-install # Skip npm ci (faster reruns)
npm run certify:local -- --keep-services # Don't stop Supabase after
Requires: Node.js 20+. Optional: Docker (for local Supabase DB tests), Playwright browsers (npx playwright install chromium).
The script refuses to run if NEXT_PUBLIC_SUPABASE_URL points to production.
Deployment
| Target | Command | URL |
|---|
| Main app | vercel --prod (from root) | waaiio.com |
| Staging | vercel --prod (staging branch) | staging.waaiio.com |
| Admin | cd admin && vercel --prod | admin.waaiio.com |
| Admin staging | cd admin && vercel --prod (staging) | admin-staging.waaiio.com |
Vercel Pro -- charges per deploy. Always ask before deploying.
Note: Vercel env vars are in the "blowded" project, not "waaiio".
Note: Admin VITE_API_URL must use https://www.waaiio.com (non-www redirects strip POST body).
Key Conventions
- Always commit and push after changes -- don't ask, just do it
- Changelog: every PR adds
changelog/unreleased/YYYY-MM-DD-<branch-name>.md (date, files, impact); fragments are collected into CHANGELOG.md before each release (see changelog/README.md)
- Payment status enum:
pending, success, failed, refunded (not "completed")
- Booking status enum:
pending, confirmed, in_progress, completed, no_show, cancelled
- Bot escape words: cancel, exit, quit, stop, restart, start over (6 languages)
- Bot error messages: "Something went wrong on our end" (never "Oops" or slang)
- Gateway follows business:
businesses.payment_gateway overrides country default
- Multi-tenant isolation:
business_id is the partition key; RLS enforces it
Security
Request protection
- CSRF: Origin check in middleware for all mutating methods (POST/PUT/PATCH/DELETE)
- Rate limiting: Per-route + global middleware via Upstash Redis (in-memory fallback)
- Session binding: IP + User-Agent tracking
Secrets
- Token encryption: AES-256-GCM for stored Meta tokens
- Service keys never exposed to client (
SUPABASE_SERVICE_ROLE_KEY, META_APP_SECRET, etc.)
- Inline tokens refused -- always use env vars
Database
- RLS fully hardened: No
USING(true) on user-facing tables
- Business ownership verified before mutations (
owner_id = auth.uid())
- SECURITY DEFINER functions go in private schemas, never public
- Atomic RPCs for concurrent-safe operations (slot booking, loyalty points, donations)
Webhook signatures
- HMAC verification mandatory on all 5 payment gateways
timingSafeEqual for all token/OTP comparisons- Fail-closed: rejects if webhook secret env var is unset
Webhook Idempotency
All payment webhooks follow the same pattern:
- Verify signature -- HMAC with
timingSafeEqual, reject if secret env var unset
- Verify amount -- compare webhook amount against stored
payment.amount
- Dedup check -- skip if
payment_status is already success
- Process -- update payment status, record platform fee, send confirmation
- Mark completed -- set
payment_status = 'success'
Gateway-specific: Stripe checks amount_total, Paystack checks kobo, Square checks total_money.amount, PayPal checks amount.
Contributing
Read CLAUDE.md before making changes. Key requirements:
- Pre-change checklist: Read the file, grep all callers, verify DB types, check two-function traps
- Verify after changing:
npx next build + npm run test + trace every code path
- Security lens: RLS on new tables, no exposed secrets, sanitized filters, verified webhooks
- Log in the changelog: add a fragment in
changelog/unreleased/ with date, what changed, which files, what could break (CLAUDE.md rule 16)
Common tasks
| Task | Steps |
|---|
| New dashboard page | Create app/dashboard/{name}/page.tsx, add to Sidebar.tsx with capability gate |
| New bot flow | Create lib/bot/flows/{name}.flow.ts, register in registry.ts |
| New capability | Add to CapabilityId union + CAPABILITIES + CAPABILITY_TIER_REQUIREMENTS in lib/capabilities/types.ts |
| New migration | supabase migration new <name>, rename to NNN_, run via Management API |
