Payload Collection Design

Patterns for designing Payload CMS collections that power the Business-as-Code system.

Core Principle

Every Collection is a Noun. Every Noun renders beautifully.

Collection (Payload) → Noun (schema.org.ai) → Component (mdxui)

Collection Domains

Collections are organized by domain in packages/db.sb/src/collections/:

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

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:

1. Noun type in schema.org.ai
2. TypeScript interface in payload-types.ts
3. Zod schema for validation
4. 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

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

Anti-Patterns

DON'T:

• Create duplicate fields across collections (normalize)
• Use inconsistent naming (follow vocabulary table)
• Skip access control (security first)
• Create deeply nested structures (flatten with relationships)

DO:

• Keep collections focused (single responsibility)
• Use relationships over embedding
• Add hooks for derived data
• Document with JSDoc comments