> For the complete documentation index, see [llms.txt](https://gotts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gotts.gitbook.io/docs/monorepo-infrastructure/monorepo/01-overview.md).

# Overview

> **Part of**: [Monorepo Infrastructure PRD](/docs/monorepo-infrastructure/monorepo.md) | **Last Updated**: 2026-02-19

***

## Executive Summary

The Gotts monorepo infrastructure provides the foundation for all packages in the `gotts-monorepo` repository. It standardizes package management, build tooling, TypeScript configuration, testing, linting, publishing, and developer experience across the entire codebase.

This PRD specifies a **pnpm 9.x + Turborepo 2.8+** monorepo using the `@gotts.ai` npm scope. Every configuration file is designed to be complete and copy-pasteable — no implicit knowledge required.

## Migration: yarn 4.x → pnpm 9.x

The original CLAUDE.md specified yarn 4.x as the package manager. This PRD documents a **deliberate migration to pnpm 9.x** based on the following analysis:

| Factor                  | yarn 4.x (Berry)                              | pnpm 9.x                                                            | Winner |
| ----------------------- | --------------------------------------------- | ------------------------------------------------------------------- | ------ |
| Dependency isolation    | PnP or `nodeLinker: node-modules`             | Strict symlinked `node_modules` by default                          | pnpm   |
| Disk efficiency         | Varies by linker mode                         | Content-addressable store, hardlinks                                | pnpm   |
| Install speed           | Fast with PnP, slower with node-modules       | Consistently fast, incremental installs                             | pnpm   |
| Turborepo integration   | Supported but pnpm is primary target          | First-class support, auto-detection                                 | pnpm   |
| Ecosystem compatibility | PnP has edge cases; node-modules mode is safe | Near-universal compatibility                                        | pnpm   |
| Lockfile readability    | `yarn.lock` (custom format)                   | `pnpm-lock.yaml` (YAML, git-friendly)                               | pnpm   |
| Workspace protocol      | `workspace:*`                                 | `workspace:*` (identical)                                           | Tie    |
| Community momentum      | Declining adoption                            | Growing; default in Turborepo docs, T3 stack, most modern monorepos | pnpm   |

**Decision**: pnpm 9.x. The strict `node_modules` isolation prevents phantom dependencies (packages used but not declared in `package.json`), Turborepo treats pnpm as the primary integration target, and the content-addressable store significantly reduces disk usage across workspaces.

> **Note**: Since nothing is implemented yet, this is a clean adoption — not a runtime migration. The only change needed is updating CLAUDE.md references from `yarn` to `pnpm`.

## Goals

1. **Zero-friction onboarding** — `pnpm install && pnpm dev` works from a fresh clone
2. **Sub-second incremental builds** — Turborepo caching ensures only changed packages rebuild
3. **Type-safe across boundaries** — Shared TypeScript configs with strict mode, no `any` leaks
4. **Publishable from day one** — `@gotts.ai` scope, Changesets versioning, npm provenance
5. **Consistent code quality** — ESLint 10 + Prettier + commitlint enforced in CI and pre-commit
6. **Copy-pasteable configs** — Every config file in this PRD is complete and ready to use
7. **Modern toolchain** — No deprecated tools; all choices are actively maintained as of Feb 2026

## Non-Goals

1. **Nx migration** — Turborepo is sufficient; Nx adds complexity without proportional benefit at this scale
2. **Bazel / Buck2** — Overkill for a TypeScript + Solidity monorepo
3. **Monorepo-as-a-service** — No hosted build cache in v1 (Turborepo remote cache is optional)
4. **Runtime bundling** — tsdown is for library publishing only; Next.js handles its own bundling
5. **Solidity tooling** — Foundry configuration is out of scope (covered in Vault PRD)
6. **Docker / containerization** — Deployment infrastructure is a separate concern

## Principles

### 1. Explicit Over Implicit

Every dependency is declared. Every config is checked in. No magic resolution, no undocumented globals, no "it works on my machine" paths.

### 2. Internal Packages First

Most workspace packages are consumed only within the monorepo. These use the **internal packages pattern** — TypeScript source is imported directly via `exports` conditions, with no build step required. Only packages published to npm get a tsdown build.

### 3. Strict by Default

TypeScript `strict: true`, ESLint `recommended` + `strict-type-checked`, pnpm strict isolation. Loosen only when there is a documented reason.

### 4. Single Source of Truth

One shared TypeScript config. One shared ESLint config. One Prettier config. Packages extend — never duplicate.

### 5. Incremental Adoption

The infrastructure rolls out in phases (see [09-implementation.md](/docs/monorepo-infrastructure/monorepo/09-implementation.md)). Each phase is independently useful and shippable.

## Package Inventory

The monorepo contains these workspace packages (current and planned):

| Package                      | Scope                         | Type                                      | Published         |
| ---------------------------- | ----------------------------- | ----------------------------------------- | ----------------- |
| `packages/core`              | `@gotts.ai/core`              | Config I/O, errors, constants (primitive) | Yes               |
| `packages/chain`             | `@gotts.ai/chain`             | ETH math, address utils, RPC (primitive)  | No (internal)     |
| `packages/crypto`            | `@gotts.ai/crypto`            | P-256 key gen, signing, DER (primitive)   | No (internal)     |
| `packages/policy`            | `@gotts.ai/policy`            | Privy policy DSL (primitive)              | No (internal)     |
| `packages/wallet`            | `@gotts.ai/wallet`            | Wallet abstraction (Privy + local)        | Yes               |
| `packages/test-utils`        | `@gotts.ai/test-utils`        | Shared MSW handlers + fixtures            | No (internal dev) |
| `packages/safe`              | `@gotts.ai/safe`              | MCP server (147 tools)                    | Yes               |
| `packages/vault`             | `@gotts.ai/vault`             | Vault SDK + contracts                     | Yes               |
| `packages/agent-proxy`       | `@gotts.ai/agent-proxy`       | Time-delay proxy                          | Yes               |
| `packages/typescript-config` | `@gotts.ai/typescript-config` | Shared tsconfig bases                     | No (internal)     |
| `packages/eslint-config`     | `@gotts.ai/eslint-config`     | Shared ESLint flat config                 | No (internal)     |
| `packages/ui`                | `@gotts.ai/ui`                | Shared React components + design tokens   | No (internal)     |
| `packages/devenv`            | `@gotts.ai/devenv`            | Uniswap devenv (local testnet)            | No (internal)     |
| `packages/testnet`           | `@gotts.ai/testnet`           | Generic EVM test toolkit                  | Yes               |
| `packages/create`            | `@gotts.ai/create`            | Install wizard CLI                        | Yes               |
| `packages/portal`            | `@gotts.ai/portal`            | Local Portal UI                           | Yes               |
| `apps/web`                   | —                             | Next.js debug UI                          | No (app)          |

> **Convention**: Packages in `packages/` are libraries (published or internal). Packages in `apps/` are deployable applications. Shared configs live in `packages/` with the internal packages pattern. See [prd/monorepo/11-primitive-packages.md](/docs/monorepo-infrastructure/monorepo/11-primitive-packages.md) for the 6 new primitive packages specification.

## Toolchain Summary

| Layer              | Tool                        | Version    | Purpose                                     |
| ------------------ | --------------------------- | ---------- | ------------------------------------------- |
| Package management | pnpm                        | 9.x        | Workspace management, dependency resolution |
| Task orchestration | Turborepo                   | 2.8+       | Build graph, caching, watch mode            |
| Language           | TypeScript                  | 5.8+       | Type safety, `erasableSyntaxOnly`           |
| Build (published)  | tsdown                      | latest     | Library bundling (ESM + CJS)                |
| Build (internal)   | —                           | —          | No build; direct TS imports via `exports`   |
| Test               | Vitest                      | 4.0+       | Unit + integration testing                  |
| Lint               | ESLint                      | 10.x       | Code quality, flat config                   |
| Format             | Prettier                    | 3.5+       | Code formatting                             |
| Sort imports       | eslint-plugin-perfectionist | latest     | Deterministic import ordering               |
| Git hooks          | Husky                       | 9.x        | Pre-commit hook runner                      |
| Staged lint        | lint-staged                 | 16.x       | Run linters on staged files only            |
| Commit lint        | commitlint                  | 19.x       | Conventional commit enforcement             |
| Versioning         | Changesets                  | 2.x        | Version management, changelogs              |
| Dependency audit   | Knip                        | latest     | Unused dependency detection                 |
| Version sync       | Syncpack                    | latest     | Cross-workspace version consistency         |
| Dependency updates | Renovate                    | —          | Automated dependency PRs                    |
| CSS                | Tailwind CSS                | v4         | Utility-first, CSS-first config             |
| UI components      | shadcn/ui                   | latest     | Copy-paste component library                |
| Framework          | Next.js                     | 15.5+ / 16 | React framework for apps                    |
| Runner             | tsx                         | latest     | TypeScript execution (dev scripts)          |