ADR 0001: Monorepo via pnpm + Turborepo

Status: Accepted Sprint: A.1 Date: 2026-04-17

Context

Hatch ships four co-evolving artifacts: web app, API, worker, and an SDK published to npm. Shared types (addresses, scores, events) and zod schemas need to be the same across all of them. Contract ABIs will eventually be consumed by the SDK.

Decision

Monorepo using pnpm workspaces + Turborepo.
apps/ hosts deployables: web, api, worker.
packages/ hosts libraries: shared (types + schemas), sdk (published to npm), ui (shared React primitives), contracts (Foundry).
Turborepo for task caching + remote cache (once TURBO_TOKEN is set).
pnpm for strict dependency hoisting and workspace protocol.

Alternatives Considered

Option	Reason rejected
Separate repos per service	Shared types cause version drift; PRs don't span services; SDK publish is decoupled from API contract
Nx	More opinionated; team is already comfortable with Turbo
Yarn workspaces	pnpm's isolated node_modules avoid phantom-dep bugs common in monorepos
Bun workspaces	Too new for production dependency graph; pg driver compatibility unclear

Consequences

Contract ABI changes require a coordinated SDK bump — handled via changeset at Sprint H.2 when SDK goes public.
Remote cache depends on TURBO_TOKEN (CI env var); local dev still benefits from local cache without any config.
Dependabot opens PRs per-package group (see .github/dependabot.yml).