Payload CMS

# MISSION: Scaffold "Payload CMS" Production Architecture
You are an expert Senior Staff Software Architect and Full-Stack Engineer. Your mission is to scaffold and implement a production-grade, highly reliable, and modular codebase following the proven architecture of **Payload CMS**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Payload CMS
- **What It Does**: Payload CMS is an open-source, MIT-licensed, Next.js-native headless CMS and application framework that installs into an existing /app folder, with swappable MongoDB, PostgreSQL, SQLite, or Cloudflare D1 database adapters.
- **Domain & Category**: Next.js-Native Headless CMS & App Framework
- **Production Scale**: 6-20 people
- **Development Mode**: HYBRID
- **Architectural Rationale**: A pnpm and Turborepo monorepo lets one core package share a common database-adapter export shape across MongoDB, Postgres, SQLite, and D1, while GraphQL, storage providers, and deployment templates stay in separate packages so a project only pulls in the pieces its target host and database actually need.
- **Live Website Reference**: https://payloadcms.com
- **Source Repository**: https://github.com/payloadcms/payload
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: TypeScript, Next.js, React, GraphQL, MongoDB, PostgreSQL, SQLite, Drizzle, pnpm, Turborepo
- **Primary Language(s)**: TypeScript, CSS, JavaScript
- **License of the reference repo**: MIT
- **Frontend**: React — Renders the admin panel shipped by packages/ui and packages/next.; Next.js — Payload installs its admin UI and API routes directly into an existing Next.js app folder.
- **Backend & APIs**: TypeScript — Language for the entire monorepo; by far the largest language by bytes in the repo.; Next.js — packages/next wires Payload’s REST, GraphQL and admin routes into Next.js route handlers.; GraphQL — Optional GraphQL API shipped as a separate package with its own payload-graphql bin, peer-depending on graphql.
- **Data & persistence**: MongoDB — Official adapter (@payloadcms/db-mongodb) built on Mongoose.; PostgreSQL — Official adapter (@payloadcms/db-postgres) built on Drizzle, re-exported through a drizzle-proxy module.; SQLite — Official adapter (@payloadcms/db-sqlite) built on Drizzle with libsql, sharing the same drizzle-proxy export shape as the Postgres adapter.; Drizzle — Shared ORM layer (@payloadcms/drizzle) underlying the Postgres, SQLite, Vercel Postgres and D1 adapters.
- **Infrastructure & deploy**: pnpm — Workspace manager for the monorepo, with a workspace-level catalog pinning shared dependency versions.; Turborepo — Orchestrates cross-package build/lint/dev tasks; build:core explicitly filters out plugin and template packages.; Vercel — templates/with-vercel-postgres, with-vercel-mongodb and with-vercel-website target Vercel deployment specifically.
- **Tooling, testing & ops**: Model Context Protocol — packages/plugin-mcp exposes Payload collections and operations to MCP clients.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/payloadcms/payload @ 9a2cdcb)
1. **Four database adapters share one export contract**: packages/db-postgres/package.json and packages/db-sqlite/package.json both expose ./drizzle, ./drizzle/relations, and a driver-specific subpath (pg-core vs sqlite-core/libsql) through a drizzle-proxy directory, so switching from Postgres to SQLite (or to db-vercel-postgres or db-d1-sqlite) means swapping the adapter package, not the calling code.
2. **Payload installs into an existing Next.js /app folder, not a standalone server**: The repository tree has an app/(payload) route group alongside the user’s own app/(app) routes, and packages/next is the package that wires Payload’s admin UI, REST, and GraphQL handlers into Next.js route handlers, matching the README’s claim of installing "directly in your existing /app folder."
3. **GraphQL ships as an optional package, not a core dependency**: packages/graphql/package.json lists graphql as a peerDependency (not a dependency) and exposes its own payload-graphql binary, so projects that only need the REST or Local API do not pull in graphql-scalars or graphql-http.
4. **Turborepo build:core deliberately excludes plugins, storage adapters, and app templates**: The root package.json build:core script runs turbo build with --filter "!@payloadcms/plugin-*" --filter "!@payloadcms/storage-*" --filter "!blank" --filter "!blank-tanstack" --filter "!website" --filter "!ecommerce", keeping the everyday build loop to core packages while build:all covers everything.
5. **Upload storage backends are one package per cloud provider**: packages/storage-azure, storage-gcs, storage-r2, storage-s3, and storage-vercel-blob each wrap a specific provider’s SDK behind the same plugin-cloud-storage interface, so a project picks one storage package instead of configuring a generic multi-provider client.
6. **Deployment templates target specific hosts by name**: templates/with-vercel-postgres, templates/with-vercel-mongodb, and templates/with-cloudflare-d1 are separate, host-specific starter templates rather than one generic template with environment-variable switches, so the database-and-host combination is chosen at project creation time via create-payload-app.
---
## 4. NON-NEGOTIABLE ARCHITECTURAL GUARDRAILS
1. **Monorepo & Modular Separation**:
   - Structure as a Turborepo monorepo with strict package boundaries:
     - `apps/web`: Application UI, routing, layouts, and server endpoints.
     - `packages/ui`: Shared design tokens, CSS variables, and Radix UI primitive components.
     - `packages/db`: Database schemas, client singleton, declarative migrations, and seed scripts.
     - `packages/config`: Shared TypeScript, ESLint, and build configurations.
2. **Strict Type Safety & Zero `any` Policy**:
   - Enable `strict: true`, `noImplicitAny: true`, and `strictNullChecks: true`.
   - Validate ALL external inputs, API request bodies, and query parameters with **Zod** schemas before execution.
3. **Frontend & Rendering Guidelines**:
   - Utilize Next.js 15 App Router: default to React Server Components (RSC) for data fetching. Handle mutations through Server Actions with Zod validation. Keep 'use client' directives restricted strictly to interactive leaf components.
4. **Design System & Aesthetics**:
   - Keep every color, radius, shadow and font in a single token file (CSS variables) and consume tokens everywhere; never hardcode hex values in components.
   - Prefer crisp 1px borders and one subtle shadow scale over blurry default shadows. Pair one sans-serif for body/headings with one monospace for tags, badges, metrics, and code.
5. **Data Layer & Reliability**:
   - Write declarative schema definitions with foreign keys, composite indexes on queried filters, and automated timestamp triggers.
   - Use connection pooling and prepared statements for serverless database execution.
---
## 5. STEP-BY-STEP SCAFFOLDING ROADMAP
- **Phase 1: Workspace & Root Config**: Initialize package manager, monorepo configuration (`turbo.json`, `tsconfig.base.json`, `package.json`).
- **Phase 2: Database Schema & Client**: Set up the data layer (MongoDB, PostgreSQL, SQLite, Drizzle): client, connection pool, models, and migration scripts.
- **Phase 3: Design Tokens & UI Primitives**: Build accessible `Button`, `Input`, `Card`, `Badge`, and layout wrappers inside `packages/ui`.
- **Phase 4: Core Application Routes & Handlers**: Implement primary authentication, user session handling, and application routes.
- **Phase 5: Quality Assurance & Build Verification**: Run `tsc --noEmit`, ESLint, Prettier, and smoke test suites to ensure zero compilation or runtime errors.
---
## 6. EXECUTION INSTRUCTIONS
1. Review all specifications, architectural guardrails, and stack choices above.
2. Present the full monorepo directory tree structure.
3. Systematically generate the complete, production-ready codebase according to the 5-phase roadmap above — starting with the root workspace setup, followed by the database schema, UI design system package, and full-stack application routes until the repository is fully scaffolded and ready to run.