# payloadcms/payload architecture

> Architecture diagram of the GitHub repository payloadcms/payload, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/payloadcms/payload
- Repository: https://github.com/payloadcms/payload

## Overview

Payload is an embeddable, extensible headless CMS and app framework. Its user-facing workflow is to manage content through the React admin, expose it through REST or GraphQL, and consume it in an application; the README also highlights authentication, drafts and versions, localization, rich text, access control, hooks, and live preview. The graph preserves those capabilities and sampled internal layers, but many runtime links remain unshown: arrows are limited to relationships evidenced by the README or sampled source index/excerpts.

Main entry points: [`packages/payload/src/collections/config/types.ts`](https://github.com/payloadcms/payload/blob/main/packages/payload/src/collections/config/types.ts) (Content Model), [`packages/payload/src/uploads/fileVersioning/cloudStorage.ts`](https://github.com/payloadcms/payload/blob/main/packages/payload/src/uploads/fileVersioning/cloudStorage.ts) (Cloud File Versions), [`packages/ui`](https://github.com/payloadcms/payload/tree/main/packages/ui) (Admin UI), [`packages/next/src/routes/rest/index.ts`](https://github.com/payloadcms/payload/blob/main/packages/next/src/routes/rest/index.ts) (REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content["Content and Admin"]
  node_editor["Admin UI"]
  node_contentmodel["Content Model<br/>[types.ts]"]
  node_richtext["Rich Text"]
  node_localization["Localization"]
  node_hooks["Lifecycle Hooks<br/>[types.ts]"]
  node_versions["Drafts and Versions<br/>[saveVersion.ts]"]
end

subgraph group_api["API and Queries"]
  node_rest["REST API<br/>[index.ts]"]
  node_graphql["GraphQL API<br/>[handler.ts]"]
  node_querybuild["Query Builder<br/>[buildQuery.ts]"]
  node_queryoperators["Query Operators<br/>[operatorMap.ts]"]
  node_mongodbqueries["Mongo Queries"]
end

subgraph group_identity["Auth and Access"]
  node_authops["Auth Operations<br/>[me.ts]"]
  node_refresh["Token Refresh<br/>[refresh.ts]"]
  node_access["Access Control<br/>[types.ts]"]
end

subgraph group_media["Uploads and Versions"]
  node_uploadpaths["Upload Paths"]
  node_fileversions["File Versioning"]
  node_storedfiles["Stored Files<br/>[storedFiles.ts]"]
  node_cleanup["File Cleanup<br/>[cleanup.ts]"]
  node_transformplan["Transform Planning"]
  node_cloudfiles["Cloud File Versions<br/>[cloudStorage.ts]"]
end

subgraph group_extensions["Extensions and Preview"]
  node_plugins["Plugins"]
  node_livepreview["Live Preview<br/>[useLivePreview.ts]"]
end

node_visitor(("Content User"))
node_app["Frontend App"]

node_visitor -.->|"manages content"| node_editor
node_editor -.->|"edits content"| node_contentmodel
node_contentmodel -.->|"supports editing"| node_richtext
node_contentmodel -.->|"supports localized content"| node_localization
node_contentmodel -.->|"configures hooks"| node_hooks
node_contentmodel -.->|"configures access"| node_access
node_contentmodel -.->|"supports drafts"| node_versions
node_app -.->|"requests content"| node_rest
node_app -.->|"queries content"| node_graphql
node_rest -->|"routes via index"| node_graphql
node_rest -.->|"queries through adapter"| node_querybuild
node_querybuild -->|"uses operators"| node_queryoperators
node_app -.->|"queries database"| node_mongodbqueries
node_contentmodel -.->|"configures uploads"| node_uploadpaths
node_cloudfiles -->|"runs file plan"| node_fileversions
node_cloudfiles -->|"collects file references"| node_storedfiles
node_cloudfiles -->|"schedules cleanup"| node_cleanup
node_cloudfiles -->|"saves versions"| node_versions
node_app -.->|"plans transforms"| node_transformplan
node_editor -.->|"enables preview"| node_livepreview
node_contentmodel -.->|"extends through plugins"| node_plugins
node_visitor -.->|"authenticates"| node_authops
node_authops -.->|"refreshes session"| node_refresh

click node_editor "https://github.com/payloadcms/payload/tree/main/packages/ui"
click node_contentmodel "https://github.com/payloadcms/payload/blob/main/packages/payload/src/collections/config/types.ts"
click node_richtext "https://github.com/payloadcms/payload/tree/main/packages/richtext-lexical"
click node_localization "https://github.com/payloadcms/payload/tree/main/packages/translations"
click node_hooks "https://github.com/payloadcms/payload/blob/main/packages/payload/src/collections/config/types.ts"
click node_rest "https://github.com/payloadcms/payload/blob/main/packages/next/src/routes/rest/index.ts"
click node_graphql "https://github.com/payloadcms/payload/blob/main/packages/next/src/routes/graphql/handler.ts"
click node_querybuild "https://github.com/payloadcms/payload/blob/main/packages/drizzle/src/queries/buildQuery.ts"
click node_queryoperators "https://github.com/payloadcms/payload/blob/main/packages/drizzle/src/queries/operatorMap.ts"
click node_mongodbqueries "https://github.com/payloadcms/payload/blob/main/packages/db-mongodb/src/queries/sanitizeQueryValue.ts"
click node_authops "https://github.com/payloadcms/payload/blob/main/packages/payload/src/auth/operations/me.ts"
click node_refresh "https://github.com/payloadcms/payload/blob/main/packages/payload/src/auth/operations/refresh.ts"
click node_access "https://github.com/payloadcms/payload/blob/main/packages/payload/src/collections/config/types.ts"
click node_versions "https://github.com/payloadcms/payload/blob/main/packages/payload/src/versions/saveVersion.ts"
click node_uploadpaths "https://github.com/payloadcms/payload/blob/main/packages/payload/src/uploads/generateFilePathOrURL.ts"
click node_fileversions "https://github.com/payloadcms/payload/blob/main/packages/payload/src/uploads/fileVersioning/fileOperationManager.ts"
click node_storedfiles "https://github.com/payloadcms/payload/blob/main/packages/payload/src/uploads/fileVersioning/storedFiles.ts"
click node_cleanup "https://github.com/payloadcms/payload/blob/main/packages/payload/src/uploads/fileVersioning/cleanup.ts"
click node_transformplan "https://github.com/payloadcms/payload/blob/main/packages/payload/src/uploads/transformers/planTransformerPipeline.ts"
click node_cloudfiles "https://github.com/payloadcms/payload/blob/main/packages/payload/src/uploads/fileVersioning/cloudStorage.ts"
click node_plugins "https://github.com/payloadcms/payload/tree/main/packages"
click node_livepreview "https://github.com/payloadcms/payload/blob/main/packages/live-preview-react/src/useLivePreview.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_editor,node_contentmodel,node_richtext,node_localization,node_hooks,node_versions,node_visitor,node_app toneBlue
class node_rest,node_graphql,node_querybuild,node_queryoperators,node_mongodbqueries toneAmber
class node_authops,node_refresh,node_access toneMint
class node_uploadpaths,node_fileversions,node_storedfiles,node_cleanup,node_transformplan,node_cloudfiles toneRose
class node_plugins,node_livepreview toneIndigo
```

## Components

### Content and Admin

- [Admin UI](https://github.com/payloadcms/payload/tree/main/packages/ui): `packages/ui`
- [Content Model](https://github.com/payloadcms/payload/blob/main/packages/payload/src/collections/config/types.ts): `packages/payload/src/collections/config/types.ts`
- [Rich Text](https://github.com/payloadcms/payload/tree/main/packages/richtext-lexical): `packages/richtext-lexical`
- [Localization](https://github.com/payloadcms/payload/tree/main/packages/translations): `packages/translations`
- [Lifecycle Hooks](https://github.com/payloadcms/payload/blob/main/packages/payload/src/collections/config/types.ts): `packages/payload/src/collections/config/types.ts`
- [Drafts and Versions](https://github.com/payloadcms/payload/blob/main/packages/payload/src/versions/saveVersion.ts): `packages/payload/src/versions/saveVersion.ts`

### API and Queries

- [REST API](https://github.com/payloadcms/payload/blob/main/packages/next/src/routes/rest/index.ts): `packages/next/src/routes/rest/index.ts`
- [GraphQL API](https://github.com/payloadcms/payload/blob/main/packages/next/src/routes/graphql/handler.ts): `packages/next/src/routes/graphql/handler.ts`
- [Query Builder](https://github.com/payloadcms/payload/blob/main/packages/drizzle/src/queries/buildQuery.ts): `packages/drizzle/src/queries/buildQuery.ts`
- [Query Operators](https://github.com/payloadcms/payload/blob/main/packages/drizzle/src/queries/operatorMap.ts): `packages/drizzle/src/queries/operatorMap.ts`
- [Mongo Queries](https://github.com/payloadcms/payload/blob/main/packages/db-mongodb/src/queries/sanitizeQueryValue.ts): `packages/db-mongodb/src/queries/sanitizeQueryValue.ts`

### Auth and Access

- [Auth Operations](https://github.com/payloadcms/payload/blob/main/packages/payload/src/auth/operations/me.ts): `packages/payload/src/auth/operations/me.ts`
- [Token Refresh](https://github.com/payloadcms/payload/blob/main/packages/payload/src/auth/operations/refresh.ts): `packages/payload/src/auth/operations/refresh.ts`
- [Access Control](https://github.com/payloadcms/payload/blob/main/packages/payload/src/collections/config/types.ts): `packages/payload/src/collections/config/types.ts`

### Uploads and Versions

- [Upload Paths](https://github.com/payloadcms/payload/blob/main/packages/payload/src/uploads/generateFilePathOrURL.ts): `packages/payload/src/uploads/generateFilePathOrURL.ts`
- [File Versioning](https://github.com/payloadcms/payload/blob/main/packages/payload/src/uploads/fileVersioning/fileOperationManager.ts): `packages/payload/src/uploads/fileVersioning/fileOperationManager.ts`
- [Stored Files](https://github.com/payloadcms/payload/blob/main/packages/payload/src/uploads/fileVersioning/storedFiles.ts): `packages/payload/src/uploads/fileVersioning/storedFiles.ts`
- [File Cleanup](https://github.com/payloadcms/payload/blob/main/packages/payload/src/uploads/fileVersioning/cleanup.ts): `packages/payload/src/uploads/fileVersioning/cleanup.ts`
- [Transform Planning](https://github.com/payloadcms/payload/blob/main/packages/payload/src/uploads/transformers/planTransformerPipeline.ts): `packages/payload/src/uploads/transformers/planTransformerPipeline.ts`
- [Cloud File Versions](https://github.com/payloadcms/payload/blob/main/packages/payload/src/uploads/fileVersioning/cloudStorage.ts): `packages/payload/src/uploads/fileVersioning/cloudStorage.ts`

### Extensions and Preview

- [Plugins](https://github.com/payloadcms/payload/tree/main/packages): `packages`
- [Live Preview](https://github.com/payloadcms/payload/blob/main/packages/live-preview-react/src/useLivePreview.ts): `packages/live-preview-react/src/useLivePreview.ts`

### Other components

- **Content User**
- **Frontend App**

## Connections

- Content User → Admin UI: manages content (evidence: `README.md`)
- Admin UI → Content Model: edits content (evidence: `README.md`)
- Content Model → Rich Text: supports editing (evidence: `README.md`)
- Content Model → Localization: supports localized content (evidence: `README.md`)
- Content Model → Lifecycle Hooks: configures hooks (evidence: `README.md`)
- Content Model → Access Control: configures access (evidence: `README.md`)
- Content Model → Drafts and Versions: supports drafts (evidence: `README.md`)
- Frontend App → REST API: requests content (evidence: `README.md`)
- Frontend App → GraphQL API: queries content (evidence: `README.md`)
- REST API → GraphQL API: routes via index
- REST API → Query Builder: queries through adapter
- Query Builder → Query Operators: uses operators (evidence: `packages/drizzle/src/types.ts`)
- Frontend App → Mongo Queries: queries database
- Content Model → Upload Paths: configures uploads (evidence: `README.md`)
- Cloud File Versions → File Versioning: runs file plan (evidence: `packages/payload/src/uploads/fileVersioning/cloudStorage.ts`)
- Cloud File Versions → Stored Files: collects file references (evidence: `packages/payload/src/uploads/fileVersioning/cloudStorage.ts`)
- Cloud File Versions → File Cleanup: schedules cleanup (evidence: `packages/payload/src/uploads/fileVersioning/cloudStorage.ts`)
- Cloud File Versions → Drafts and Versions: saves versions (evidence: `packages/payload/src/uploads/fileVersioning/cloudStorage.ts`)
- Frontend App → Transform Planning: plans transforms
- Admin UI → Live Preview: enables preview (evidence: `README.md`)
- Content Model → Plugins: extends through plugins (evidence: `README.md`)
- Content User → Auth Operations: authenticates (evidence: `README.md`)
- Auth Operations → Token Refresh: refreshes session
