Captus

An AI assistant that answers a small business's customers on WhatsApp, Instagram and Facebook Messenger, around the clock. It replies from the business's own knowledge base, takes and manages bookings, sends documents, flags hot leads, and hands the chat to a person when it should. Owners run it from a web dashboard: inbox, knowledge, bookings, templates and settings.

Built solo end to end: multi-tenant backend, AI reply loop, dashboard, landing page (captus.cc), and a test harness that runs whole conversations against a real model.

Full feature list and backlog: FEATURES.md.

How it works

flowchart LR
  C[Customer on WhatsApp / Instagram / Messenger] -->|Meta webhook| W[Fastify /webhook<br/>signature check, dedupe]
  W -->|debounced job| Q[(BullMQ on Redis)]
  Q --> K[Reply worker]
  K -->|RAG: pgvector| DB[(Postgres<br/>Row Level Security per business)]
  K -->|tools: book, cancel, send doc,<br/>hand over, hot lead| DB
  K <-->|function calling,<br/>model fallback chain| G[Gemini]
  K -->|Graph API| C
  D[Owner dashboard<br/>Next.js + Clerk] -->|REST| A[Fastify API] --> DB

• Stack: TypeScript, Fastify, BullMQ + Redis, Postgres with pgvector, Gemini, Next.js + Clerk. Hosted on Render, Neon and Vercel.
• Multi-tenant by design: every tenant table has Row Level Security, and each request runs inside its business's context, so one business can't read another's data even if a query forgets a filter. The e2e suite checks this.
• One pipeline, three channels: Messenger and Instagram customers get a prefixed id (fb_… / ig_…) in place of a phone number, so the worker, bookings and inbox are shared. Only sending and the webhook parser know the difference.

Problems worth a look

• Message bursts. People send three short messages in a row. Inbound jobs are debounced per chat so they get one combined reply, with a 20s cap so someone who keeps typing still hears back. A voice note or photo is waited for and answered together with the text around it.
• Duplicate and overlapping work. Meta redelivers webhooks it didn't get a fast ack for. Inbound messages are deduplicated by id, and a per-chat reply lock in Redis stops two workers answering the same customer at once. A booking whose confirmation fails to send is never retried, since that would risk a second booking.
• Model failures. Every Gemini error is classified (rate limit, daily quota, overload, timeout, retired model, bad output, auth, billing…) and handled differently: try the next model, retry later, or give a holding reply and alert the owner (src/lib/llmFallback.ts).
• Bookings. Services have a duration and a capacity, checked against existing bookings (and Google Calendar busy times when connected); the e2e suite races two customers for a one-person room. Reminders live in the database and are rebuilt into the queue at startup, because the free Redis has no persistence.
• Human handover races. If the owner takes over while the AI is mid-reply, that reply is dropped, unless it just made, moved or cancelled a booking.
• Measuring answer quality. npm run eval scores the assistant on 52 customer messages (grounded answers, made-up-fact traps, Malay/Chinese, complaints, prompt injection, bookings, cross-business leaks) with rule checks plus an LLM judge, and reports pass rates, invented-fact rate, handover recall, latency and tokens. It caught small hallucinations ("our signature latte") and overpromising, and showed the trade-off of the prompt fix. Results and what they mean: docs/eval.md.
• Testing an LLM product. e2e/ boots the real backend and workers against throwaway Postgres + Redis in Docker, a mock Meta Graph API and the real Gemini. 54 conversation scenarios, failure injection (Postgres down, Redis wiped, model retired, sends refused) and a load test of 50 chats at once.

Layout

Path	What
src/	Backend: Fastify API + BullMQ workers, one process (src/main.ts)
src/routes/	Meta webhook, dashboard API, admin API, Google OAuth, document downloads
src/lib/	AI reply loop (gemini.ts, llmFallback.ts, systemPrompt.ts), booking, templates, reminders, follow-ups, WhatsApp / Messenger clients (whatsapp.ts, messenger.ts, channels.ts)
src/db/	Postgres access + schema.sql (every tenant table uses Row Level Security)
src/scripts/	CLI helpers (onboard, ingest, link-user, status, create-reminder-template)
dashboard/	Owner dashboard (Next.js + Clerk). See dashboard/README.md
landing/	Static landing page for captus.cc
e2e/	End-to-end stress harness (mock Meta, real Gemini)
docs/archive/	Original architecture and MVP plan, kept for reference only

Run locally

docker compose up -d          # Postgres (pgvector) + Redis
cp .env.example .env          # fill in WhatsApp, Gemini and Clerk keys
npm install
npm run migrate
npm run dev                   # API on :3000
npm run dev:worker            # workers (separate terminal)

To get Meta's webhooks to your machine, run a tunnel (e.g. cloudflared tunnel --url http://localhost:3000). Then set <tunnel>/webhook as the callback in the Meta app.

Tests

npm run typecheck
npm run e2e                   # all phases; needs Docker Desktop
npm run e2e scenarios         # or: failures | load
E2E_ONLY=booking npm run e2e  # one scenario by name
npm run eval                  # answer-quality eval, see docs/eval.md

The e2e run uses the real GEMINI_API_KEY, and a full run uses a large share of the free daily quota.

Production

Piece	Where
Backend + workers	Render free web service captus-backend (Singapore), api.captus.cc, from render.yaml
Redis	Render free Key Value captus-redis. No persistence: queued jobs are lost on restart. Reminders are rebuilt from the DB at startup.
Postgres	Neon free, ap-southeast-1
Dashboard	Vercel project captus-cc, app.captus.cc
Landing	Vercel, captus.cc
Uptime	UptimeRobot pings https://api.captus.cc/health every 5 min (keeps Render's free tier awake)

Pushing to main deploys everything. Migrations run on every boot (they're idempotent). Operator alerts show up in the Render logs as [OPS ALERT] and are sent to OWNER_NOTIFY_NUMBER on WhatsApp.