payload-contracts/CLAUDE.md

payload-contracts

Shared TypeScript types, API client, and block registry for Payload CMS multi-tenant frontends.

Purpose

This package is the single source of truth for TypeScript types between the CMS (sv-payload) and all frontend sites (sv-frontend / Plesk production servers). It prevents type drift and provides a consistent API client across all frontends.

Architecture

CMS (payload-cms)                    Contracts (this repo)                Frontends
━━━━━━━━━━━━━━━━                    ━━━━━━━━━━━━━━━━━━━━                ━━━━━━━━━
payload-types.ts ──extract-types──→  src/types/payload-types.ts
                                     src/types/collections.ts    ←────  import { Page, Post }
                                     src/types/blocks.ts         ←────  import { Block, BlockByType }
                                     src/types/media.ts          ←────  import { getImageUrl }
                                     src/types/api.ts            ←────  import { PaginatedResponse }
                                     src/api-client/             ←────  import { createPayloadClient }
                                     src/blocks/registry.ts      ←────  import { createBlockRenderer }

Commands

pnpm install          # Install dependencies
pnpm build            # Compile TypeScript
pnpm typecheck        # Type-check without emitting
pnpm extract          # Re-extract types from CMS (run on sv-payload)

Updating Types

When CMS collections or blocks change:

1. On sv-payload: cd ~/payload-cms && pnpm payload generate:types
2. On sv-payload: cd ~/payload-contracts && pnpm extract
3. Review changes, commit, push
4. Write a work order in work-orders/ if frontends need updating

Key Files

File	Purpose
src/types/payload-types.ts	Full auto-generated types from CMS
src/types/collections.ts	Curated frontend collection re-exports
src/types/blocks.ts	Block union type + BlockByType helper
src/types/media.ts	Media type + image URL helpers
src/types/api.ts	PaginatedResponse, query params, error types
src/api-client/index.ts	createPayloadClient() factory
src/blocks/registry.ts	createBlockRenderer() factory
src/constants/tenants.ts	Tenant IDs and slugs
scripts/extract-types.ts	Type extraction from payload-types.ts

Tenants

ID	Slug	Site
1	porwoll	porwoll.de
4	c2s	complexcaresolutions.de
5	gunshin	gunshin.de
9	blogwoman	blogwoman.de

Work Orders

The work-orders/ directory is the coordination mechanism between the CMS (sv-payload) and all frontends (sv-frontend / Plesk production). When a CMS change requires frontend updates, a work order is created.

Structure

work-orders/
├── _template.md              # Template for new work orders
├── YYYY-MM-DD-slug.md        # Active work orders
└── completed/                # Archived completed work orders

Creating a Work Order (on sv-payload)

cd ~/payload-contracts

# After CMS changes: extract types + create work order
./scripts/create-work-order.sh "Add stats-block" --extract

# Or manually: create from template
cp work-orders/_template.md work-orders/$(date +%Y-%m-%d)-my-change.md
# Edit, then commit + push

Executing a Work Order (on sv-frontend)

When you receive a work order (via git pull on the contracts repo):

1. Read the work order in work-orders/ — it contains the exact TypeScript interface, implementation steps, and reference code
2. Update contracts: pnpm update @c2s/payload-contracts (or pnpm install)
3. Implement the changes described in the work order
4. Verify: pnpm lint && pnpm build
5. Commit and push to develop

Or use the orchestration script from sv-payload:

./scripts/execute-work-order.sh work-orders/2026-02-15-add-stats-block.md

Work Order Lifecycle

sv-payload                              sv-frontend
━━━━━━━━━━                              ━━━━━━━━━━━
1. Change CMS block/collection
2. pnpm payload generate:types
3. cd ~/payload-contracts
4. pnpm extract
5. ./scripts/create-work-order.sh "Title"
6. Edit work order (add interface, steps)
7. git add -A && git commit && git push
                                         8. git pull (contracts repo)
                                         9. Read work order
                                        10. pnpm update @c2s/payload-contracts
                                        11. Implement block/changes
                                        12. pnpm lint && pnpm build
                                        13. git commit && git push (develop)
14. Verify result
15. Move to completed/:
    mv work-orders/X.md work-orders/completed/
    git commit && git push

Block Implementation Pattern

When implementing a new block from a work order, follow this pattern:

// src/components/blocks/MyNewBlock.tsx
import type { BlockByType } from '@c2s/payload-contracts/types'

type MyNewBlockData = BlockByType<'my-new-block'>

interface MyNewBlockProps {
  block: MyNewBlockData
}

export function MyNewBlock({ block }: MyNewBlockProps) {
  // block is fully typed from the contracts
  return (
    <section>
      <h2>{block.title}</h2>
      {/* ... */}
    </section>
  )
}

Then register in the block renderer:

// src/components/blocks/index.tsx
import { MyNewBlock } from './MyNewBlock'

const blockComponents = {
  // ... existing blocks
  'my-new-block': MyNewBlock,
}

Scripts

Script	Location	Purpose
pnpm extract	sv-payload	Extract types from CMS payload-types.ts
create-work-order.sh	sv-payload	Create a new work order with metadata
execute-work-order.sh	sv-payload	Orchestrate work order execution on sv-frontend

Git Workflow

• main branch only — tag releases as v1.x.x
• Frontends consume via Git dependency in package.json