# puckeditor/puck architecture

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

- Interactive diagram: https://gitdiagram.com/puckeditor/puck
- Repository: https://github.com/puckeditor/puck

## Overview

Puck is a modular visual editor for authoring React pages with application-owned components and data. The main workflow is configuring components and fields, editing page data in the Puck interface, publishing that data through the host application, then rendering it as a React page. The graph also preserves documented React-framework usage and sampled slot, Contentful-field, and AI integration capabilities. Core runtime wiring beyond the supplied excerpts is represented conservatively; unsampled relationships are omitted.

Main entry points: [`packages/core/components/Puck/index.tsx`](https://github.com/puckeditor/puck/blob/main/packages/core/components/Puck/index.tsx) (Puck editor), [`packages/core/components/Render/index.tsx`](https://github.com/puckeditor/puck/blob/main/packages/core/components/Render/index.tsx) (React renderer), [`packages/core/store/index.ts`](https://github.com/puckeditor/puck/blob/main/packages/core/store/index.ts) (Editor state), [`packages/core/types/Data.tsx`](https://github.com/puckeditor/puck/blob/main/packages/core/types/Data.tsx) (Page data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Visual authoring"]
  node_component_config["Component config<br/>[Config.tsx]"]
  node_puck_editor["Puck editor<br/>[index.tsx]"]
  node_editor_ui["Editor panels<br/>[index.tsx]"]
  node_canvas["Canvas and drop zones<br/>[index.tsx]"]
  node_outline["Layer outline<br/>[index.tsx]"]
  node_publish["Publish callback<br/>[index.tsx]"]
  node_demo_config["Demo component config<br/>[server.tsx]"]
end

subgraph group_runtime["Page rendering"]
  node_render_api["React renderer<br/>[index.tsx]"]
  node_slot_render["Slot renderer<br/>[server.tsx]"]
  node_server_render["Server rendering<br/>[index.tsx]"]
end

subgraph group_data["Data and fields"]
  node_app_state["Editor state<br/>[index.ts]"]
  node_reducer["State actions<br/>[index.ts]"]
  node_data_ops["Page data operations"]
  node_auto_fields["Field controls<br/>[index.tsx]"]
  node_rich_text["Rich text editing<br/>[index.ts]"]
  node_page_data["Page data<br/>[Data.tsx]"]
end

subgraph group_integrations["Integrations"]
  node_external_field["Contentful field<br/>[index.ts]"]
  node_contentful[("Contentful service")]
  node_ai_handler["Puck AI handler<br/>[route.ts]"]
  node_puck_cloud["Puck Cloud"]
  node_next_recipe["Next.js recipe<br/>[page.tsx]"]
  node_router_recipe["React Router recipe<br/>[puck-splat.tsx]"]
end

node_editor_user(("Editor user"))
node_host_app["Host application"]

node_editor_user -->|"edits pages"| node_puck_editor
node_host_app -->|"provides config and data"| node_puck_editor
node_puck_editor -->|"renders interface"| node_editor_ui
node_puck_editor -->|"renders canvas"| node_canvas
node_puck_editor -->|"manages state"| node_app_state
node_canvas -->|"updates page"| node_app_state
node_outline -->|"updates structure"| node_app_state
node_editor_ui -->|"edits fields"| node_auto_fields
node_auto_fields -.->|"uses field adapter"| node_external_field
node_external_field -->|"fetches entries"| node_contentful
node_app_state -->|"dispatches actions"| node_reducer
node_reducer -->|"changes page data"| node_data_ops
node_app_state -->|"holds"| node_page_data
node_puck_editor -->|"publishes data"| node_publish
node_publish -->|"passes page data"| node_host_app
node_host_app -->|"persists"| node_page_data
node_host_app -->|"renders saved page"| node_render_api
node_render_api -->|"uses config"| node_component_config
node_render_api -->|"uses data"| node_page_data
node_render_api -->|"renders slots"| node_slot_render
node_slot_render -->|"resolves components"| node_component_config
node_server_render -->|"server-renders"| node_render_api
node_host_app -.->|"routes AI requests"| node_ai_handler
node_ai_handler -.->|"delegates requests"| node_puck_cloud
node_next_recipe -->|"hosts editor"| node_puck_editor
node_router_recipe -->|"hosts editor"| node_puck_editor
node_demo_config -->|"defines components"| node_component_config
node_rich_text -->|"edits rich text"| node_page_data

click node_component_config "https://github.com/puckeditor/puck/blob/main/packages/core/types/Config.tsx"
click node_puck_editor "https://github.com/puckeditor/puck/blob/main/packages/core/components/Puck/index.tsx"
click node_editor_ui "https://github.com/puckeditor/puck/blob/main/packages/core/components/Puck/components/Layout/index.tsx"
click node_canvas "https://github.com/puckeditor/puck/blob/main/packages/core/components/Puck/components/Canvas/index.tsx"
click node_outline "https://github.com/puckeditor/puck/blob/main/packages/core/components/LayerTree/index.tsx"
click node_app_state "https://github.com/puckeditor/puck/blob/main/packages/core/store/index.ts"
click node_reducer "https://github.com/puckeditor/puck/blob/main/packages/core/reducer/index.ts"
click node_data_ops "https://github.com/puckeditor/puck/tree/main/packages/core/lib/data"
click node_auto_fields "https://github.com/puckeditor/puck/blob/main/packages/core/components/AutoField/index.tsx"
click node_rich_text "https://github.com/puckeditor/puck/blob/main/packages/core/components/RichTextEditor/index.ts"
click node_external_field "https://github.com/puckeditor/puck/blob/main/packages/field-contentful/index.ts"
click node_publish "https://github.com/puckeditor/puck/blob/main/packages/core/components/Puck/index.tsx"
click node_page_data "https://github.com/puckeditor/puck/blob/main/packages/core/types/Data.tsx"
click node_render_api "https://github.com/puckeditor/puck/blob/main/packages/core/components/Render/index.tsx"
click node_slot_render "https://github.com/puckeditor/puck/blob/main/packages/core/components/SlotRender/server.tsx"
click node_server_render "https://github.com/puckeditor/puck/blob/main/packages/core/components/ServerRender/index.tsx"
click node_ai_handler "https://github.com/puckeditor/puck/blob/main/recipes/next-ai/app/api/puck/%5B...all%5D/route.ts"
click node_next_recipe "https://github.com/puckeditor/puck/blob/main/recipes/next/app/%5B...puckPath%5D/page.tsx"
click node_router_recipe "https://github.com/puckeditor/puck/blob/main/recipes/react-router/app/routes/puck-splat.tsx"
click node_demo_config "https://github.com/puckeditor/puck/blob/main/apps/demo/config/server.tsx"

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_component_config,node_puck_editor,node_editor_ui,node_canvas,node_outline,node_publish,node_demo_config,node_editor_user toneBlue
class node_render_api,node_slot_render,node_server_render toneAmber
class node_app_state,node_reducer,node_data_ops,node_auto_fields,node_rich_text,node_page_data toneMint
class node_external_field,node_contentful,node_ai_handler,node_puck_cloud,node_next_recipe,node_router_recipe toneRose
class node_host_app toneIndigo
```

## Components

### Visual authoring

- [Component config](https://github.com/puckeditor/puck/blob/main/packages/core/types/Config.tsx): `packages/core/types/Config.tsx`
- [Puck editor](https://github.com/puckeditor/puck/blob/main/packages/core/components/Puck/index.tsx): `packages/core/components/Puck/index.tsx`
- [Editor panels](https://github.com/puckeditor/puck/blob/main/packages/core/components/Puck/components/Layout/index.tsx): `packages/core/components/Puck/components/Layout/index.tsx`
- [Canvas and drop zones](https://github.com/puckeditor/puck/blob/main/packages/core/components/Puck/components/Canvas/index.tsx): `packages/core/components/Puck/components/Canvas/index.tsx`
- [Layer outline](https://github.com/puckeditor/puck/blob/main/packages/core/components/LayerTree/index.tsx): `packages/core/components/LayerTree/index.tsx`
- [Publish callback](https://github.com/puckeditor/puck/blob/main/packages/core/components/Puck/index.tsx): `packages/core/components/Puck/index.tsx`
- [Demo component config](https://github.com/puckeditor/puck/blob/main/apps/demo/config/server.tsx): `apps/demo/config/server.tsx`

### Page rendering

- [React renderer](https://github.com/puckeditor/puck/blob/main/packages/core/components/Render/index.tsx): `packages/core/components/Render/index.tsx`
- [Slot renderer](https://github.com/puckeditor/puck/blob/main/packages/core/components/SlotRender/server.tsx): `packages/core/components/SlotRender/server.tsx`
- [Server rendering](https://github.com/puckeditor/puck/blob/main/packages/core/components/ServerRender/index.tsx): `packages/core/components/ServerRender/index.tsx`

### Data and fields

- [Editor state](https://github.com/puckeditor/puck/blob/main/packages/core/store/index.ts): `packages/core/store/index.ts`
- [State actions](https://github.com/puckeditor/puck/blob/main/packages/core/reducer/index.ts): `packages/core/reducer/index.ts`
- [Page data operations](https://github.com/puckeditor/puck/tree/main/packages/core/lib/data): `packages/core/lib/data`
- [Field controls](https://github.com/puckeditor/puck/blob/main/packages/core/components/AutoField/index.tsx): `packages/core/components/AutoField/index.tsx`
- [Rich text editing](https://github.com/puckeditor/puck/blob/main/packages/core/components/RichTextEditor/index.ts): `packages/core/components/RichTextEditor/index.ts`
- [Page data](https://github.com/puckeditor/puck/blob/main/packages/core/types/Data.tsx): `packages/core/types/Data.tsx`

### Integrations

- [Contentful field](https://github.com/puckeditor/puck/blob/main/packages/field-contentful/index.ts): `packages/field-contentful/index.ts`
- **Contentful service**
- [Puck AI handler](https://github.com/puckeditor/puck/blob/main/recipes/next-ai/app/api/puck/%5B...all%5D/route.ts): `recipes/next-ai/app/api/puck/[...all]/route.ts`
- **Puck Cloud**
- [Next.js recipe](https://github.com/puckeditor/puck/blob/main/recipes/next/app/%5B...puckPath%5D/page.tsx): `recipes/next/app/[...puckPath]/page.tsx`
- [React Router recipe](https://github.com/puckeditor/puck/blob/main/recipes/react-router/app/routes/puck-splat.tsx): `recipes/react-router/app/routes/puck-splat.tsx`

### Other components

- **Editor user**
- **Host application**

## Connections

- Editor user → Puck editor: edits pages
- Host application → Puck editor: provides config and data
- Puck editor → Editor panels: renders interface
- Puck editor → Canvas and drop zones: renders canvas
- Puck editor → Editor state: manages state
- Canvas and drop zones → Editor state: updates page
- Layer outline → Editor state: updates structure
- Editor panels → Field controls: edits fields
- Field controls → Contentful field: uses field adapter
- Contentful field → Contentful service: fetches entries
- Editor state → State actions: dispatches actions
- State actions → Page data operations: changes page data
- Editor state → Page data: holds
- Puck editor → Publish callback: publishes data
- Publish callback → Host application: passes page data
- Host application → Page data: persists
- Host application → React renderer: renders saved page
- React renderer → Component config: uses config
- React renderer → Page data: uses data
- React renderer → Slot renderer: renders slots
- Slot renderer → Component config: resolves components
- Server rendering → React renderer: server-renders
- Host application → Puck AI handler: routes AI requests
- Puck AI handler → Puck Cloud: delegates requests
- Next.js recipe → Puck editor: hosts editor
- React Router recipe → Puck editor: hosts editor
- Demo component config → Component config: defines components
- Rich text editing → Page data: edits rich text
