agentic-dev/docs/architecture/overview.md

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