​
Decisions

Clay keeps architecture decision records as small Markdown files under docs/decisions/. Each record captures the decision, the rationale, and the consequences.
Records are authored under docs/decisions/ in the canonical Clay repository for review and version control. The card links below point to that source of truth; they require the repository to be reachable from your network. This Mintlify page is the navigation index — the decision text itself lives in the repo, not in this site.

​
Index

0001. Initial stack

Cloudflare Worker backend, Hono, Mastra, Hyperdrive, Next.js static landing.
The index above lists every ADR under docs/decisions/. When you add a new record, append a <Card> here in the same change so the published navigation stays complete.

​
ADR format

Each record is a small Markdown file under docs/decisions/ with YAML frontmatter (title, description). The body follows the lightweight MADR shape: context, decision, consequences, and any alternatives that were considered and rejected.
Records are intentionally short. A page that needs diagrams, large code blocks, or multi-page reasoning belongs in a maintained spec under apps/specs/, not in an ADR.

​
How to add a new decision

ADRs are the durable, low-churn source of truth for “why Clay is the way it is.” Anyone working in the canonical Clay repository can add one. The full contribution contract lives in docs/decisions/AGENTS.md; the steps below are the short version.
1

Pick the next number

List docs/decisions/ and pick the next sequential four-digit prefix (0002, 0003, …). The directory on disk is the source of truth — never guess the next number.
2

Branch and draft

Create a feature branch (for example adr/0002-<short-slug>) and add a new file under docs/decisions/ named NNNN-kebab-case-slug.md. The file is plain Markdown, not MDX.
3

Author the record

Add YAML frontmatter (title, and optionally description and date) and the required body sections: ## Decision, ## Rationale, and ## Consequences. State the decision, why it was made, and what it commits the project to. Keep it short — diagrams and long reasoning belong in a maintained spec under apps/specs/, not in the ADR.
4

Review and merge

Open a pull request that links the ADR file. Reviewers confirm the frontmatter, the sequential prefix, and that the decision is genuinely new (not a silent edit of an existing record). Merge once approved.
5

Update this index

In the same change, add a <Card> entry under the Index above pointing to the new ADR’s GitHub blob URL (https://github.com/curlyz/clay/blob/main/docs/decisions/NNNN-slug.md). The index must list every ADR under docs/decisions/ — readers navigate from here.
6

Verify frontmatter

Run pnpm md:frontmatter to confirm the new ADR passes the frontmatter check before merging.

​
Filename and frontmatter

  • Filename: NNNN-kebab-case-slug.md (for example 0002-worker-queues-for-jobs.md).
  • Frontmatter: at minimum title. The Mintlify frontmatter checker enforces this; you can also include description and date for context.
ADRs are immutable. To revisit a decision, author a new ADR that supersedes the old one and link both from the index. Do not edit a committed record.

ADR contribution contract

The full rules, layout, and verification steps for docs/decisions/ live in docs/decisions/AGENTS.md in the canonical Clay repository.

Glossary

Terms used across Clay’s product and platform — the vocabulary ADRs and product specs share.

Architecture

The backend, landing, mobile, specs, and generated client surfaces ADRs shape over time.

Intentions

The product-side direction decisions are written to protect.