# Clean Architecture Monorepo Template

## Quick Start

```bash
pnpm install          # Install all dependencies
pnpm dev              # Start all dev servers
pnpm build            # Build all packages
pnpm test             # Run all tests
pnpm turbo boundaries # Validate workspace dependency graph
docker compose up -d  # Start PostgreSQL
```

## Project Overview

Turborepo + pnpm monorepo organized by vertical features. Each feature (`auth`, `blog`, `media`, `marketing-pages`, `navigation`) owns its Clean Architecture layers. Core packages (`core-shared`, `core-cms`, `core-api`, `core-trpc`, `core-ui`) provide foundation. Two tooling packages (`core-eslint`, `core-typescript`) provide shared configs. Workspace boundaries are enforced by ESLint (lint-time) and Turborepo (build-graph time). Supports Next.js and TanStack Start as frontend frameworks, Payload CMS for content management, and comprehensive agent-optimized documentation.

## Read First

- `AGENTS.md` — Package map, boundary rules, per-package conventions
- `docs/architecture/overview.md` — High-level architecture and package responsibilities
- `docs/architecture/vertical-feature-spec.md` — Design spec with rationale and decision log
- `docs/guides/adding-a-feature.md` — End-to-end new feature walkthrough

## Key Conventions

- **Relative imports in `src/`** — Source files use relative paths (`../repositories/...`), not `@/` alias
- **`@/` alias in tests** — Test files (`*.test.ts`) use `@/` to import from `src/`
- **`vitest.config.ts`** — Every package must define `resolve.alias: { "@": path.resolve(__dirname, "./src") }`
- **`tsconfig.json` rootDir** — Set `"rootDir": "."` so TypeScript finds both `src/` and test files
- **Payload repositories via constructor** — Feature packages receive Payload config at constructor time, not as a direct dependency
- **App bootstrap** — Each app calls `bindProduction*()` per feature at startup to wire Payload into InversifyJS containers

## MCP Servers

Start Storybook before UI work: `pnpm dev --filter @repo/storybook`

Storybook MCP available at `http://localhost:6006/mcp` — use `list-all-documentation` to discover existing components before creating new ones.

## Key Ports

| Service | Port |
|---|---|
| Next.js | 3000 |
| Payload CMS | 3001 |
| TanStack Start | 3002 |
| PostgreSQL | 5432 |
| Storybook | 6006 |