Quick start

From a fresh clone to the assistant answering questions about a claim on a local machine. Allow ten minutes, most of it loading data.

Prerequisites

Tool	Version	Why
Node.js	22 or later	The workspace sets engines.node >= 22. Tests also use Node's built-in node:sqlite.
npm	10 or later	One npm workspace: packages/*, api, frontend.
A Gemini API key	Google AI Studio	Chat, voice and the claim generator. Not needed for the test suites.
Git	any

Wrangler, Vite and everything else come in as dev dependencies. A Cloudflare login is needed only to deploy or to reach the remote D1 database.

Run it

1. Install the workspace.

   npm install

2. Create the local secrets file and add the Gemini key to it.

   cp api/.dev.vars.example api/.dev.vars

   api/.dev.vars is gitignored. It holds GEMINI_API_KEY and, if the AI Gateway is on, CF_AIG_TOKEN. See Configuration for everything else it can hold.

3. Create the local database schema. Local development uses Cloudflare D1, which wrangler dev runs as a SQLite file under api/.wrangler/state.

   npm run db:migrate

4. Load some claims. Either copy the shared data set from Neon (needs DATABASE_URL in .dev.vars), or generate a few with Gemini.

   npm run copy-claims -- --from neon --to d1-local
   # or
   npm run generate -- --lob auto --count 5

5. Start the Worker and the front end.

   npm run dev

   The Worker listens on :8787 and Vite on :5173, proxying /api (including the voice WebSocket) to the Worker.

6. Open the app at http://localhost:5173. The root URL opens a random claim. Open the chat launcher bottom-right and ask "Was the policy in force at the date of loss?".

Check it worked

• http://localhost:8787/api/health reports the store and the model in use, and whether the AI Gateway is on.
• The chat shows an activity chip such as Reading the policy… before the answer, and a lookups link under it.
• http://localhost:5173/claimpanion.html shows the embedded version inside a pretend claims system. In development Vite serves the element at the URL the built bundle will occupy, so no separate build is needed.

If the chat answers with an AI Gateway error, see the runbook.

Run the tests

Neither suite needs a key, a database or a network connection.

npm test            # Vitest: shared, API and front end, in seconds
npm run test:e2e    # build, then Playwright against the real Worker with a scripted model

The first Playwright run on a machine needs its browser: npx playwright install chromium. See Testing.

Reset

• Delete api/.wrangler/state to start the local database again from nothing.
• Clear site data in the browser to reset Prompt Lab versions, the chat dock position and the region.

Next

• Configuration: every variable, and where each one lives.
• Repository tour: what is where.
• Architecture overview: how it fits together.