# ADR-0001 — Stack and monorepo layout

Status: accepted, 2026-11-09.

# Context

The brief asks for a public registry with a web UI, a versioned REST API, a CLI, an SDK and an MCP server, maintained mostly by one person with Claude Code, deployed on the owner's own cluster.

# Decision

• One pnpm workspace. No Turborepo: there are five small packages and no build graph worth caching.
• apps/web — Next.js 16 (App Router), React 19, TypeScript, Tailwind 4. It serves the UI, the REST API under /api/v1 and the MCP endpoint at /mcp from one process and one port.
• apps/web/src/server — all business logic as plain TypeScript modules with no Next.js imports. The API entry point is handleApi(request): Response. Next route handlers, the admin console and the tests all call the same functions.
• packages/registry-core — everything the CLI, API and MCP server must agree on: manifest schema, limits, scopes, tar codec, validator, scanner, install adapters.
• packages/db, packages/sdk, packages/cli, apps/registry-mcp as described in the repository map.
• Workspace packages are consumed as TypeScript source (exports point at src/*.ts). Next transpiles them; tsx runs scripts; the CLI is bundled with esbuild for distribution.
• Validation with zod 4. Password hashing with @node-rs/argon2. Tests with Vitest and Playwright.

No separate apps/api, packages/ui or packages/config: they would add indirection without a second consumer.

# Consequences

• One deployable, one port, one PM2 process. Simple to operate; no horizontal scaling without first addressing ADR-0004.
• The API is testable without booting Next.js.
• A future split of the API into its own service is mechanical because the router has no framework dependency.