Repository tour
One npm workspace, strict TypeScript everywhere. Three workspaces (packages/shared, api, frontend) plus database migrations, tests and these docs.
Top level
| Path | What it is |
|---|---|
package.json | Workspace root and the root scripts |
tsconfig.base.json | Strict TypeScript settings every workspace extends |
tsconfig.json | Root tooling only: typechecks e2e/ and the test configs |
vitest.config.ts | Unit and integration tests: one project per workspace, coverage gates |
playwright.config.ts | End-to-end tests against the Worker started by e2e/server.ts |
e2e/ | Playwright specs, the test Worker launcher and its offline worker.env |
db/ | SQL migrations per store, and migrate.mjs for Neon |
docs/ | The original Markdown guides (integration guide, embedded design note, testing) |
docusaurus/ | This site |
.github/workflows/test.yml | CI: typecheck, Vitest with coverage, Playwright, reference-docs check |
CLAUDE.md | The working conventions, in brief, for anyone (human or agent) changing the code |
packages/shared: the contract
Everything the Worker and the browser must agree on. Nothing here does I/O.
| File | Holds |
|---|---|
claim.ts | The Claim document as a zod schema: the contract everything else is built on |
taxonomy.ts | Data domains from the DGPH-34 ontology, lines of business, statuses, coverages, risk flag codes |
chat.ts | The wire protocol: ChatRequest, the SSE ChatEvent union, ClientAction, MATTER_PANELS |
capabilities.ts | The public capability catalogue: id, label, description, group, pinned, quick-action message |
feedback.ts | Answer feedback: the vote request, the reason list, the report shape |
fixtures/ | Three hand-written claims: the generator's worked examples and the test fixtures |
api: the Worker
| Path | Holds |
|---|---|
wrangler.jsonc | Worker config: assets, the D1 binding, vars; env.neon for the Neon deployment |
src/index.ts | The Hono app: middleware, /api/* routes, health, the SPA fallback |
src/access.ts | CORS against ALLOWED_ORIGINS, and the optional EMBED_KEY |
src/env.ts · src/context.ts | Bindings and per-request services (claims, AI, feedback) |
src/ai/ | The AiProvider port, the Gemini and scripted adapters, the AI Gateway |
src/chat/ | Prompt assembly, the claim brief, the turn loop, the SSE route |
src/capabilities/ | Shared tools, one file per capability group, the registry, the tool runner |
src/prompts/ | The prompt catalogue (all prompt text), resolution, fingerprints, the read-only route |
src/claims/ · src/feedback/ | Each a port, a D1 adapter, a Neon adapter and routes |
src/voice/relay.ts | The WebSocket relay to Gemini Live |
src/generator/ | Scenario briefs and the claim generator |
scripts/ | The CLIs: generate-claims.ts, copy-claims.ts, and lib/stores.ts |
test/ | The D1 shim over in-memory SQLite, builders, and the whole-app integration test |
frontend: the browser
| Path | Holds |
|---|---|
src/App.tsx | The shell: providers, top bar, US left rail, routes, the chat in popover or docked form |
src/claimpilot/ | Claim screens: claimView.ts (every number on screen), MatterHome (UK), the US Claim page, lists, demo hints |
src/chat/ | The widget, the dock, useChat (SSE loop and feedback), useVoice, the feedback card, the capability menu |
src/embed/ | The <claimpilot-assistant> custom element and its shadow-root stylesheet |
src/promptlab/ | The Prompt Lab, its browser-held version store, the feedback report |
src/region/ | UK and US: chrome, palette, formats, currency |
src/lib/ | The typed API client (including the SSE reader) and formatters |
src/styles.css · src/index.css | Theme tokens shared with the element; page-level rules for the app only |
public/claimpanion.html | Claimpanion: a pretend host claims system embedding the element |
vite.embed.config.ts | The second build: the element as one script |
Where tests live
Unit tests sit beside the code they test as *.test.ts(x), in every workspace. Integration helpers are in api/test/ and frontend/test/. End-to-end specs are in e2e/. See Testing.
Rules worth knowing before changing anything
These are the conventions in CLAUDE.md, and the reason the codebase stays small:
- A capability is one
Capabilityobject in the matching group file. Its playbook lives only inapi/src/prompts/catalogue.ts; its UI row only inpackages/shared/src/capabilities.ts. - The model is reached only through
api/src/ai/provider.ts. No vendor SDK calls anywhere else. - No prompt text outside the catalogue. No claim-shape assumptions outside the contract.
system.safetyis always assembled before any claim data.- Answer feedback never enters the conversation.
- Claim generation is CLI-only. There are no in-app generation endpoints.