# ADR-0001: Monorepo with pnpm workspaces and Turborepo

- **Status:** Accepted
- **Date:** 2026-08-11

## Context

Three deployable applications (storefront, admin, API) share domain types, validation
rules and an HTTP client. Split across three repositories, every contract change becomes a
version bump, a publish and three coordinated pull requests — and in practice the types drift
because nobody wants to pay that cost for a one-field change.

## Decision

A single repository with pnpm workspaces for dependency linking and Turborepo for task
orchestration and caching. Shared code lives in `packages/*`; deployables live in `apps/*`.

`@sport/types`, `@sport/validation` and `@sport/api-client` compile to CommonJS + `.d.ts`
because NestJS consumes them at runtime. `@sport/ui` ships raw TypeScript and is compiled by
each Next.js app via `transpilePackages` — no build step, no watcher, faster HMR.

Versions that must stay identical across the workspace (TypeScript, React, Next, Zod, ESLint)
are pinned once in the `catalog:` block of `pnpm-workspace.yaml`.

## Consequences

A backend field rename surfaces as a frontend type error in the same commit. One
lockfile, one CI pipeline, one lint configuration. The cost is a heavier initial install and
the need for discipline about dependency direction (ADR-0004), which the ESLint boundary rules
enforce mechanically.

## Alternatives considered

Polyrepo with a private npm registry — rejected: the publish/consume loop is
slower than the entire feature it serves. Nx — comparable, but Turborepo's smaller surface fits
a team that wants a build cache, not a build framework.