# Architecture Overview

## Clean Architecture Monorepo

This template implements Uncle Bob's Clean Architecture in a Turborepo + pnpm monorepo. The core principle: **dependencies point inward only**.

```
┌─────────────────────────────────────────────────┐
│  Frameworks & Drivers (outermost)               │
│  Next.js, TanStack Start, Payload CMS,          │
│  Storybook, PostgreSQL, Docker                  │
│  ┌─────────────────────────────────────────┐    │
│  │  Interface Adapters                     │    │
│  │  tRPC routers, Controllers, Presenters  │    │
│  │  ┌─────────────────────────────────┐    │    │
│  │  │  Application (Use Cases)        │    │    │
│  │  │  Business logic, interfaces     │    │    │
│  │  │  ┌─────────────────────────┐    │    │    │
│  │  │  │  Entities (innermost)   │    │    │    │
│  │  │  │  Models, Errors, Zod    │    │    │    │
│  │  │  └─────────────────────────┘    │    │    │
│  │  └─────────────────────────────────┘    │    │
│  └─────────────────────────────────────────┘    │
└─────────────────────────────────────────────────┘
```

## Package Map

```
packages/core         → Clean architecture (entities, use cases, infra, DI)
packages/api          → tRPC routers (calls core controllers)
packages/api-client   → Shared React Query hooks + provider
packages/cms-core     → Payload CMS config, collections, hooks
packages/cms-client   → Dual-mode Payload client (local + HTTP)
packages/ui           → Atomic Design + shadcn/ui + Tailwind v4

apps/web-next         → Next.js 15 reference app
apps/web-tanstack     → TanStack Start reference app
apps/cms              → Thin Next.js shell for Payload admin
apps/storybook        → Centralized Storybook instance
```

## Data Flow

```
UI → useQuery(trpc.content.list) → tRPC Router → Controller → Use Case → Repository → Payload Local API → PostgreSQL
```

## Key Design Decisions

- **InversifyJS DI** — symbol-based resolution, documented in di/AGENTS.md
- **Dual-mode CMS client** — Local API for server-side (no HTTP overhead), HTTP for external
- **Atomic Design** — atoms/molecules/organisms/templates, co-located stories
- **tRPC single data path** — all data (including CMS content) flows through tRPC
- **Agent-optimized docs** — AGENTS.md at every level with rules, recipes, tables