​
Backend overview

apps/backend is a small Cloudflare Worker that hosts Clay’s HTTP API. Keep it as a direct Hono app until the API surface is large enough to justify more structure.

​
Layout

apps/backend/
├── AGENTS.md             Backend workspace contract
├── README.md             Mirror of this page for humans reading the repo
├── package.json          @clay/backend scripts and dependencies
├── tsconfig.json
├── wrangler.toml         Cloudflare Worker config (clay-backend)
├── src/
│   ├── AGENTS.md         Source-folder conventions
│   ├── CLAUDE.md         Pointer
│   └── index.ts          Hono app, route handlers, OpenAPI document
├── scripts/
│   ├── AGENTS.md         Scripts-folder conventions
│   ├── CLAUDE.md         Pointer
│   └── export-openapi.ts Generates apps/backend/openapi/openapi.yaml
└── openapi/
    ├── AGENTS.md         Generated-bundle conventions
    ├── CLAUDE.md         Pointer
    └── openapi.yaml      Generated — do not hand-edit
The Worker is named clay-backend and listens on src/index.ts. The single [vars] entry (APP_ENV = "development") is non-secret and committed to source. No bindings are declared today — see Environment and bindings.

​
Boundaries

1

Hono handlers validate at the boundary

Define route schemas with Zod and @hono/zod-openapi next to the handler that serves the route. Every request (params, query, body, headers) is rejected with a typed 4xx when the schema fails.
2

OpenAPI 3.1, not 3.0

The contract is OpenAPI 3.1. The Worker exposes the document at runtime through app.doc31("/openapi.json", ...) and at build time through getOpenApiDocument(). Do not downgrade.
3

Keep the backend flat while it is small

Do not add dependency injection, containers, repository layers, or service folders before the code needs them.
4

Split only by pressure

When routes grow, extract route files first. Add services only when repeated business logic appears in more than one handler.
5

OpenAPI stays in sync

pnpm --filter @clay/backend generate exports the OpenAPI document from the live Hono app. The generated YAML feeds @clay/client via Fern.
Do not commit database URLs. When database access lands, Hyperdrive is the intended Worker runtime connection boundary. Land the [[hyperdrive]] block and the consumer in the same change.
See API reference for the current HTTP surface, OpenAPI pipeline for the export pipeline, and Deploy for publishing.

API reference

The implemented routes, schemas, and OpenAPI source.

Deploy

The Wrangler commands used to publish the Worker.

Architecture

The full Turborepo surface layout this backend lives inside.