agentic-dev/CLAUDE.md

Clean Architecture Monorepo Template

Quick Start

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

TDD

pnpm test --watch --filter @repo/<feature>   # watch one feature
pnpm test -- --coverage                      # full run with coverage
pnpm test:stories                            # Storybook smoke tests
pnpm test:e2e                                # Playwright e2e

See docs/guides/tdd-workflow.md for the full cycle.

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
• Lazar-conformant file layout — Entities live at entities/models/<x>.ts; errors at entities/errors/<domain>.ts + entities/errors/common.ts; mock siblings use the .mock.ts suffix (<x>.repository.mock.ts); real repository impls drop the payload- prefix (<x>.repository.ts); interface filenames are dot-separated (<x>.repository.interface.ts)
• Factory-function use cases & controllers — Every use case and controller is (deps) => async (input) => result; each exports export type I*UseCase = ReturnType<typeof xUseCase> (and the analogous I*Controller); one controller per use case (no multi-method controllers)
• DI uses .toDynamicValue() for factories — bind<IXUseCase>(SYMBOL).toDynamicValue((ctx) => xUseCase(ctx.container.get(...))); mocks remain the default binding
• Tests inject mocks directly — Construct MockXRepository and pass into the factory: signInUseCase(mockUsers, mockAuth)(input). No container rebinding in unit tests
• 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 swap mocks for real Payload-backed impls in the 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