alpha-chat

Standalone chat app for alpha.gov.bb (Claude-week MVP).

This is the Chat box from the architecture proposal — a separate Next.js app at / that helps citizens find services on alpha.gov.bb, surfaces content based on questions, and walks users through filling out forms before handing them off to the forms app for final review & submission.

Architecture

┌───────────────────────┐         ┌────────────────────────┐
│  alpha-chat (this)    │         │  forms app             │
│  Next.js, /           │         │  (frontend-alpha,      │
│                       │         │   later: forms repo)   │
│  - chat UI            │         │                        │
│  - /api/chat (SSE)    │ HTTP →  │  - /api/chat-form/     │
│  - calls forms app    │         │      registry          │
│                       │         │      :slug/validate    │
└───────────────────────┘         │      :slug/prefill     │
           │                      │  - form pages          │
           │ POST /retrieve       │  - submits to MDAs     │
           ▼                      └────────────────────────┘
┌───────────────────────┐
│  RAG worker (CF)      │
│  Vectorize + Workers  │
│  AI embeddings        │
└───────────────────────┘

The chat does not answer questions itself — it consumes a sitemap of content (RAG worker), surfaces relevant pages, and offers to fill in the right form. Form submission happens in the forms app after the user reviews their answers.

Required env vars

Var	Where	What
ANTHROPIC_API_KEY	server	Claude API key for the chat route
RAG_URL	server	Base URL of the Cloudflare worker (e.g. https://rag.…)
LLM_MODEL	server	Claude model id, defaults to claude-haiku-4-5
FORM_APP_BASE_URL	server	Origin of the forms app
NEXT_PUBLIC_FORM_APP_BASE_URL	client	Same as above; exposed to the browser for the redirect
NEXT_PUBLIC_CONTENT_APP_URL	client	Origin of the content app (Browse content link)

The forms-app contract

alpha-chat is decoupled from frontend-alpha's form internals. It expects the forms app to expose three JSON endpoints under ${FORM_APP_BASE_URL}:

GET /api/chat-form/registry

Returns the list of chat-eligible forms — i.e. forms whose schemas the chat can drive end-to-end. Cached server-side for 5 minutes.

{
  "entries": [
    {
      "slug": "get-birth-certificate",
      "serviceTitle": "Get a birth certificate",
      "urlMatchers": ["/get-birth-certificate"],
      "schemaSummary": "### Your details (step: applicant)\n- firstName [text] — First name\n- baby_dob [date] — Date of birth\n  ..."
    }
  ]
}

schemaSummary is rendered verbatim into the chat's system prompt. The forms app should generate it from its FormStep schemas using the same describeField helper that lived in frontend-alpha/src/lib/chat/form-fields.ts.

POST /api/chat-form/:slug/validate

Body: { "fields": { "firstName": "Aisha", "baby_dob": "2024-03-12", ... } }.

// Success
{ "ok": true, "data": { ...hydrated... } }

// Failure
{
  "ok": false,
  "errors": [
    { "field": "baby_dob", "message": "Required" }
  ]
}

POST /api/chat-form/:slug/prefill

Body: same as validate. Response:

{ "url": "https://forms.alpha.gov.bb/.../form?step=review&token=abc123" }

The forms app should stash the fields under a short-lived server-side token (or signed JWT) and have its form page rehydrate from that token on mount. sessionStorage is not cross-origin, so the old prefill mechanism does not work across two separate apps.

Local dev

npm install
ANTHROPIC_API_KEY=... \
RAG_URL=https://rag.example.workers.dev \
FORM_APP_BASE_URL=http://localhost:3001 \
NEXT_PUBLIC_FORM_APP_BASE_URL=http://localhost:3001 \
NEXT_PUBLIC_CONTENT_APP_URL=http://localhost:3001 \
  npm run dev

Open http://localhost:3000.

Re-indexing content

The RAG index lives in Cloudflare Vectorize. To rebuild it from a local content tree (e.g. frontend-alpha's src/content):

CF_ACCOUNT_ID=... CF_API_TOKEN=... \
CONTENT_DIR=/path/to/frontend-alpha/src/content \
SITE_URL=https://alpha.gov.bb \
  npm run ingest

cd worker && npx wrangler vectorize insert frontend-alpha-rag \
  --file=../vectors.ndjson

What's NOT here yet

• WhatsApp/Telegram adapters (slide 3 mentions these as a "later" goal — the webapp req/res is the MVP).
• The forms-app /api/chat-form/* endpoints — they need to be added to frontend-alpha before the form-handoff flow works. Until then the chat answers informationally but the form flow short-circuits with a clear error.
• Visual regression tests, e2e tests.