​
Architecture

Clay is a pnpm Turborepo with four app surfaces and one generated client package. 
apps/backend/   Cloudflare Worker, Hono, OpenAPI
apps/landing/   Next.js static export pitching site
apps/mobile/    Expo iOS app for intention capture and opportunity workflows
apps/specs/     Mintlify specifications site, exported to Cloudflare Pages
packages/client/ Fern-generated TypeScript client from the backend OpenAPI contract
docs/           ADRs and vendor documentation snapshots

​
Backend

1

Cloudflare Worker

The API runs as a Worker. Routing, validation, and policy all live on the edge.
2

Hono routing

HTTP routes are mounted with Hono through @hono/zod-openapi. The current backend stays flat in apps/backend/src/index.ts until route pressure justifies extraction.
3

OpenAPI 3.1

The HTTP surface is described in OpenAPI 3.1 and kept in sync with implemented routes. The document is exported from the live Hono app into apps/backend/openapi/openapi.yaml and linted by Redocly before the Fern generator consumes it.
4

@clay/client SDK

A Fern-generated TypeScript SDK in packages/client/src/generated wraps the typed resource clients and error model. The mobile app and any future Clay consumer import from @clay/client, never from the raw HTTP surface.
Mastra and Hyperdrive remain part of the intended backend stack, but they should be documented as implemented only after code exists under apps/backend/src/mastra or Worker bindings reference the database boundary. See Environment and bindings for the intended-binding rules.
See Backend overview for the implementation contract, OpenAPI pipeline for the export pipeline, and Workspace for the build/deploy surface.

​
Landing

apps/landing is the Next.js 16 static-export pitching site that explains Clay as an opportunity platform. It hosts the root route, the design-system plasticine board, and supporting pages (framework, technical, competitors) used by partners and reviewers. Copy follows the intentions/personalities/opportunity contract — never the chatbot/resume/dating framing.
See Landing page section spec for the section-by-section contract behind apps/landing/src/app/page.tsx.

​
Mobile

apps/mobile is the iOS-first Expo app. It uses Expo SDK 57, Expo Router, and @expo/ui for native form controls in the first capture flow. Haptics ship through react-native-pulsar, exposed as product-level events in apps/mobile/lib/clay-haptics.ts.
See Mobile capture flow for the current product contract and Expo UI ownership boundary, and Mobile for the iOS interaction contract.

​
Specs

apps/specs is a Mintlify workspace package. It exports to .mintlify-export/ via mint export, and Wrangler publishes that bundle to the clay-specs Cloudflare Pages project. Navigation lives in docs.json and must move with every page add, rename, or move.

​
Workspace contract

TaskCommand
Install everythingpnpm install
Run all dev serverspnpm dev
Build all appspnpm build
Typecheck everythingpnpm typecheck
Lint everythingpnpm lint
Regenerate OpenAPI + SDKpnpm generate
Format Markdown / MDX / JSONpnpm format:all
Deploy specspnpm --filter @clay/specs cf:deploy

Backend overview

The Hono + OpenAPI contract behind the backend surface.

Workspace

The pnpm + Turborepo tasks and per-package scripts that ship this layout.

Client package

The Fern-generated @clay/client SDK consumed by every Clay app.

API reference

The implemented HTTP routes and Zod schemas.

OpenAPI pipeline

How Hono route schemas become the OpenAPI YAML consumed by Fern.

Mobile capture flow

The first iOS screen wired up against this architecture.