deflock/api/CLAUDE.md

# api/

Fastify server run directly on Bun (no build step — Bun executes the TypeScript as-is).
Deployed as a long-running process on a VPS via systemd (see `.github/workflows/`), **not**
serverless. That's a load-bearing fact for how background work is structured below.

Handles everything for DeFlock that isn't OpenStreetMap map data: geocoding proxy
(Nominatim), GitHub sponsors, and the contact form.

## Conventions

- No ORM/DB. Every external service gets its own thin client class in `services/` that talks
  to that service's HTTP API directly via native `fetch` (or, where the service already has an
  official SDK in use elsewhere in this org, that SDK — e.g. `AiScreeningClient` uses the
  `openai` package). See `ZammadClient`, `NominatimClient`, `GithubClient`, `TurnstileClient`.
- Config/data that isn't a secret is checked into git and read at startup, not hardcoded and
  not fetched at runtime — e.g. `data/zipcodes-us.json`, `prompts/contact-screening.md`, and
  `kb/*.md`. Editing these requires a server restart to take effect (loaded once at module
  init).
- OpenTelemetry (`telemetry.ts`) exports logs/metrics to Grafana Cloud via a local otelcol
  sidecar. Errors are bucketed by a substring-matching `classifyErrorMessage()` in `server.ts`
  — new upstream integrations should extend that rather than inventing a separate error-typing
  scheme.
- Tests use `bun:test`. Prefer dependency injection (pass a stub client/SDK instance into the
  constructor or function) over mocking `global.fetch` when the thing being tested isn't
  itself an HTTP client — see `ContactScreeningService.test.ts` vs `ZammadClient.test.ts`.

## Contact form + AI screening

**Intent**: the volunteer support team gets more contact-form messages than they can
individually triage. Every submission that passes Cloudflare Turnstile gets a first pass from
an AI classifier before a human sees it — unless the sender explicitly opts out via a
checkbox on the form. The AI never sends anything to a customer directly; it only drafts,
tags, and prioritizes for a human to review in Zammad.

**Ordering matters**: the Zammad ticket is always created synchronously and the user gets
their success response immediately. AI screening then runs as fire-and-forget background work
*after* the response is sent — it relies on this process staying alive to finish, which is
only safe because this is a persistent server, not a serverless function. A screening failure
(OpenAI down, bad response, Zammad write failure) never blocks ticket creation or crashes the
process — it just gets tagged/logged and a human handles that ticket without AI assistance,
same as before this feature existed.

**Where the classification logic lives**: the taxonomy, tone, and per-category instructions
are entirely in `prompts/contact-screening.md` (checked into git, not in TypeScript) so
non-engineers can review/iterate on classifier behavior like any other reviewed change. Code
(`ContactScreeningService.ts`) only translates the AI's structured output into Zammad actions
(tags, priority, group, shared draft vs. internal note, scheduled close) — it deliberately
does *not* contain classification judgment calls itself, except for hard safety backstops
(e.g. force-tagging) that shouldn't depend on the model remembering a rule. When product
behavior changes (new category, new disposition), expect to change the prompt first and the
plan/orchestration code second — they're meant to stay in sync but are two different kinds of
change (policy vs. mechanism).

**Dry-run endpoint**: `POST /contact/message/dry-run` runs the same classifier + planning
logic with no Turnstile check and no Zammad writes, for testing prompt/taxonomy changes
quickly. It has no auth — fine for local dev, but don't expose it publicly without adding
some, since it's a free OpenAI-call relay otherwise.