AI Revenue Agent for home services (MVP).
Current vertical: plumbing.

CallBuddy provides a mobile-first merchant dashboard and telephony/AI pipeline:

1. Merchant signs up and completes onboarding
2. Inbound call (Twilio webhook or demo webhook) is recorded
3. AI extraction + rule engines evaluate booking readiness
4. Booking is auto-created only when safe conditions are met
5. Merchant reviews/updates calls and bookings in dashboard

• Next.js 16 (App Router) + TypeScript
• Prisma + PostgreSQL
• Auth.js (credentials)
• Tailwind CSS
• Vitest + Playwright

• Node.js >= 24 (.nvmrc)
• npm >= 10
• Docker Desktop (for local Postgres)

1. Install dependencies:

npm install

2. Start Postgres:

docker compose up -d

3. Configure environment:

cp .env.example .env.local

Or create .env.local manually:

DATABASE_URL="postgresql://prisma:prisma_password@localhost:5432/callbuddy?schema=public"
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="replace-with-at-least-16-chars"
# optional
OBSERVABILITY_ERROR_WEBHOOK_URL="https://example.com/webhook"
SEED_DEMO_PHONE_NUMBER="+12025550123"

4. Run Prisma setup:

npm run db:generate
npm run db:migrate:deploy
npm run db:seed

5. Start the app:

npm run dev

Open http://localhost:3000.

• npm run dev - start local Next.js dev server
• npm run typecheck - TypeScript validation
• npm run test - unit/integration tests (Vitest)
• npm run test:e2e - all Playwright specs
• npm run test:e2e:demo - Step22 stable demo validation spec only

CallBuddy uses a hybrid intent pipeline with ML inference support and a safety fallback path.

• ML_INTENT_MODE=SHADOW (default): run ML prediction for observability while preserving the safe intent path
• ML_INTENT_MODE=ON: apply ML prediction when available
• ML_INTENT_MODE=OFF: disable ML inference

Optional overrides:

• ML_INTENT_PYTHON_BIN (default: ml/.venv/bin/python)
• ML_INTENT_SCRIPT_PATH (default: ml/scripts/predict_intent.py)
• ML_INTENT_TIMEOUT_MS (default: 1200)

• Stable Step22 end-to-end script:
  • tests/e2e/demo-validation.spec.ts
• Runbook:
  • docs/step22-demo-validation.md
• Demo guide:
  • docs/demo-guide.md
• Optional fixed-account run:

CALLBUDDY_DEMO_EMAIL="test1@example.com" \
CALLBUDDY_DEMO_PASSWORD="SecurePass123" \
npm run test:e2e:demo

When those env vars are set, the suite reuses that merchant and seeds all demo scenarios into the same dashboard account.

• MVP supports two inbound paths:
  • Twilio voice webhook: /api/telephony/twilio/voice
  • Internal demo webhook: /api/telephony/demo/incoming
• Merchant mapping currently uses merchant_profiles.demo_phone_number.
• Optional localtunnel for Twilio testing:

npx localtunnel --port 3000

Then point Twilio Voice webhook to:

https://<your-subdomain>.loca.lt/api/telephony/twilio/voice

Recommended:

• App: Vercel
• Database: Neon Postgres (or equivalent managed Postgres)

Required env vars in deployment:

• DATABASE_URL
• NEXTAUTH_URL
• NEXTAUTH_SECRET

Optional:

• OBSERVABILITY_ERROR_WEBHOOK_URL

• Completed through Step 23: MVP polish pass