Domain	Purpose	Examples
admin	Platform admin	Users, Orgs, ApiKeys
ai	AI/ML experiments	ModelEvals, AIExperiments
api	API infrastructure	Proxies, Crawlers
business	Business entities	Businesses, Teams, Goals
code	Code artifacts	Workers, Artifacts
communications	Messaging	Messages, Sequences, Channels
compliance	Regulatory	Policies, Controls, Evidence
content	Documents	Documents, Files, Presentations
data	Ontology	Nouns, Verbs, Actions, Events
design	Visual	Themes
experiments	Testing	Experiments, Hypotheses, Variants
financial	Money	Invoices, Payments, Cards
integrations	External	Webhooks, Triggers, Providers
legal	Contracts	Contracts
marketing	Demand gen	Leads, Campaigns, Competitors
markets	Market data	Industries, Occupations, Tasks
product	Offerings	Products, Prices, Features, Offers
sales	Revenue	Deals, Quotes, Proposals
startup	Venture	Founders, CustomerSegments
success	Customers	Customers, Contacts, Subscriptions
tech	Technology	Technologies, Tools
tools	Agent tools	Browser, Computer
vibecode	Code gen	Sessions, Generations
web	Websites	Sites, Pages, Blogs, Docs
work	Execution	Tasks, Projects, Workflows, Agents

Collection Structure

import type { CollectionConfig } from 'payload'

export const Things: CollectionConfig = {
  slug: 'things',

  // Admin UI
  admin: {
    useAsTitle: 'name',
    group: 'Domain',
    defaultColumns: ['name', 'status', 'createdAt'],
  },

  // Access control
  access: {
    read: () => true,
    create: isAuthenticated,
    update: isOwnerOrAdmin,
    delete: isAdmin,
  },

  // Fields
  fields: [
    // ...
  ],

  // Hooks
  hooks: {
    beforeChange: [],
    afterChange: [],
  },
}

Field Patterns

Required Fields (every collection)

fields: [
  {
    name: 'name',
    type: 'text',
    required: true,
  },
]

Standard Optional Fields

{
  name: 'description',
  type: 'textarea',
},
{
  name: 'status',
  type: 'select',
  defaultValue: 'draft',
  options: ['draft', 'active', 'archived'],
},

Relationship Patterns

// Belongs to (many-to-one)
{
  name: 'business',
  type: 'relationship',
  relationTo: 'businesses',
  required: true,
},

// Has many (one-to-many via reverse)
// No field needed - query from child

// Many-to-many
{
  name: 'industries',
  type: 'relationship',
  relationTo: 'industries',
  hasMany: true,
},

// Polymorphic
{
  name: 'actor',
  type: 'relationship',
  relationTo: ['agents', 'humans', 'serviceAccounts'],
},

MDX Content Field

{
  name: 'content',
  type: 'richText',
  editor: lexicalEditor({
    features: ({ defaultFeatures }) => [
      ...defaultFeatures,
      // MDX support
    ],
  }),
},

Naming Conventions

Collection Slugs

Plural, lowercase, hyphenated
customer-segments, journal-entries

Field Names

camelCase
firstName, createdAt, isActive

Consistent Vocabulary

Use	Don't Use
`name`	`title`, `label`, `heading`
`description`	`subtitle`, `summary`, `body`
`status`	`state`, `phase`
`isActive`	`active`, `enabled`
`createdAt`	`created`, `dateCreated`

Access Control Patterns

// Public read
access: {
  read: () => true,
}

// Authenticated only
access: {
  read: isAuthenticated,
  create: isAuthenticated,
}

// Owner or admin
access: {
  read: isOwnerOrAdmin,
  update: isOwnerOrAdmin,
  delete: isAdmin,
}

// Org-scoped
access: {
  read: belongsToOrg,
  create: belongsToOrg,
}

Hook Patterns

Auto-populate fields

hooks: {
  beforeChange: [
    ({ data, req }) => {
      if (!data.createdBy) {
        data.createdBy = req.user?.id
      }
      return data
    },
  ],
}

Cascade updates

hooks: {
  afterChange: [
    async ({ doc, req }) => {
      // Update related records
      await req.payload.update({
        collection: 'related',
        where: { parent: { equals: doc.id } },
        data: { parentName: doc.name },
      })
    },
  ],
}

Sync to external systems

hooks: {
  afterChange: [
    async ({ doc, operation }) => {
      if (operation === 'create') {
        await stripe.customers.create({ ... })
      }
    },
  ],
}

mdxdb Integration

Collections sync bidirectionally with .mdx files via mdxdb:

.mdx file (Business-as-Code)
       ↕ mdxdb sync
Payload Collection (runtime)
       ↕ mdxdb query
ClickHouse (analytics)

MDXLD Frontmatter

---
$type: Product
$id: https://acme.com/products/widget
name: Widget Pro
price: 99
---

# {name}

Product description here...

Collection → Noun → Component

Every collection maps to:

Noun type in schema.org.ai
TypeScript interface in payload-types.ts
Zod schema for validation
mdxui component for rendering

// Collection
export const Products: CollectionConfig = { ... }

// → Generates TypeScript
interface Product {
  id: string
  name: string
  price: number
}

// → Has Zod schema
const ProductSchema = z.object({ ... })

// → Renders via mdxui
<ProductCard {...product} />
<ProductRow {...product} />
<ProductPanel {...product} />

Creating New Collections

Create file in appropriate domain: collections/{domain}/{Name}.ts
Follow field patterns above
Add to domain index: collections/{domain}/index.ts
Add to main index: collections/index.ts
Run pnpm generate:types to update payload-types.ts
Create corresponding mdxui renderer if needed

Collection Structure

Field Patterns

Required Fields (every collection)

Standard Optional Fields

Relationship Patterns

MDX Content Field

Naming Conventions

Collection Slugs

Field Names

Consistent Vocabulary

Access Control Patterns

Hook Patterns

Auto-populate fields

Cascade updates

Sync to external systems

mdxdb Integration

MDXLD Frontmatter

Collection → Noun → Component

Creating New Collections

Anti-Patterns

payload-collections

Payload Collection Design

Core Principle

Collection Domains