CushLabs Messenger

Overview

CushLabs Messenger is the platform layer for CushLabs' Facebook Messenger AI agents. It's the deployment target every CushLabs Messenger client lands on, and the architectural successor to the single-tenant ny-english-messenger-bot Worker that's been in production since the start.

The repo is shipping in two intentional phases. Phase 1 — currently live — is a bilingual voice-profile survey: clients receive a private URL, fill out a structured questionnaire, and the answers persist to Cloudflare KV under their Facebook Page ID. The operator uses that profile to configure the client's bot voice, escalation rules, and FAQ before launch. Phase 2 — post Meta App Review — extracts the full multi-tenant Messenger Worker into this repo. One Worker handles every client via page_id routing, Anthropic-powered conversations, KV-backed state, Sentry observability, and Upstash rate limiting.

The split is deliberate. Phase 1 unblocks paying client onboarding while Phase 2 is being extracted from the production reference. Nothing built for the survey is throwaway — the KV namespace, the access-code primitive, the Worker deployment, and the bilingual data layer all carry forward.

The Challenge

• Voice profiles arrived as freeform email. Tone, boundaries, FAQs, escalation triggers, language preference — every client launch needed all of it, and gathering it ad-hoc was slow, lossy, and inconsistent.
• Cloning the bot Worker per client was unsustainable. Each new client added a deployment to manage, a separate set of secrets, and a fork-divergence risk for prompt and pipeline changes.
• A relational database was overkill. The data is per-client documents — never queried in aggregate — and per-client documents already mapped naturally onto KV.
• Bilingual support couldn't be a translation afterthought. Some clients run EN, some MX-ES, some both; the data layer needs to capture the survey language at write-time, not infer it later.

The Solution

A Cloudflare Worker exposes a tiny authenticated API (GET / POST /voice-profile) keyed by per-client access codes minted via CLI. A standalone Vite + React + Tailwind 4 admin app — deployed independently to Cloudflare Pages — renders the bilingual survey, validates the access code, and saves answers back to KV under the client's page_id.

Access codes over OAuth.

• Single shareable URL per client, no accounts to provision, no password reset flow.
• Codes are single-purpose, single-client, easily rotatable; the trade-off is acceptable because the survey itself contains nothing sensitive.

KV over a relational store.

• Per-client documents map naturally onto KV's key/value model.
• Access codes (access:<code>) and voice profiles (<pageId>:voice-profile) live in the same namespace the Phase 2 bot runtime will use for conversation state.

Worker + Pages split.

• The Worker stays free of static-asset serving. The eventual bot runtime can reuse the same Worker deployment without a Pages-shaped detour.
• Pages handles the React SPA, gets free TLS, edge caching, preview deployments, and a clean Robert-managed domain story.

Bilingual at the data layer.

• Each saved profile records its lang at write time.
• Phase 2 prompts use that field directly to set Claude's response language without re-prompting the client.

Technical Highlights

• Single Worker, many clients from day one — page_id routing primitive in place; no hard-coded client identifiers anywhere.
• TypeScript strict end-to-end — Shared Env, ClientEntry, and VoiceProfile types between the Worker and the admin app via the pnpm workspace.
• CLI-minted access codes — scripts/create-client.mjs writes the access:<code> KV entry directly via Wrangler bindings; no admin UI surface, no auth-bypass risk.
• Tailwind 4 via @tailwindcss/vite — @theme blocks in CSS, no tailwind.config.* file, deprecated @astrojs/tailwind-style integrations sidestepped.
• CORS preflight handled in the Worker — Survey app is a cross-origin SPA; preflight short-circuits before any KV read.
• Phase-aware design — Every Phase 1 primitive (KV namespace, access codes, Worker bindings, bilingual schema) is reused by Phase 2; nothing is rework.
• Mexican Professional Spanish, not "neutral LatAm" — The survey, error messages, and validation copy target Mexico-based corporate professionals, not a generic Spanish reader.

Results

For the End User / Team:

• Each new client onboards via one CLI command and one URL — under 60 seconds of operator time.
• Survey persistence latency is sub-100ms typical (KV write at the edge).
• Bilingual coverage is built-in; clients pick their language and answers are tagged accordingly for Phase 2.
• Operator gets a structured, schema-validated voice profile keyed by Page ID — no spreadsheet drift, no email archaeology.

Technical Demonstration:

• Multi-tenant platform thinking applied to a real client roadmap, not a hypothetical SaaS.
• Phased architecture with explicit "carry-forward primitives" — the riskiest thing about Phase 2 is already proven by Phase 1.
• Edge-native runtime (Workers + KV + Pages) chosen for cost, latency, and operational simplicity rather than pattern-matching on what's trendy.
• Real production discipline applied to a small surface: strict TypeScript, secret hygiene, CORS scoped, license set, repo standardized.

CushLabs Messenger is the platform CushLabs' AI agent business runs on — a small, deliberate codebase that earns its complexity one client at a time.