# superdoc/docx-editor architecture

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

- Interactive diagram: https://gitdiagram.com/superdoc/docx-editor
- Repository: https://github.com/superdoc/docx-editor

## Overview

SuperDoc is a DOCX-native document engine: users open or create a DOCX, edit and review its structured content, and render or automate document operations through a shared Document API. The README documents browser editing, OOXML-backed writes, pagination, and collaboration; the source index identifies the API, editor runtime, and layout engine as substantial implementation areas. Some subsystem links below reflect README-level capability descriptions rather than inspected call sites.

Main entry points: [`packages/document-api/src/index.ts`](https://github.com/superdoc/docx-editor/blob/main/packages/document-api/src/index.ts) (Document API), [`packages/superdoc/src/core/SuperDoc.ts`](https://github.com/superdoc/docx-editor/blob/main/packages/superdoc/src/core/SuperDoc.ts) (Browser editor), [`packages/layout-engine/layout-engine/src/execution.ts`](https://github.com/superdoc/docx-editor/blob/main/packages/layout-engine/layout-engine/src/execution.ts) (Pagination and layout), [`packages/superdoc/src/core/v2-integration/v2-integration.js`](https://github.com/superdoc/docx-editor/blob/main/packages/superdoc/src/core/v2-integration/v2-integration.js) (OOXML document model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Editor entry points"]
  node_browser["Browser editor<br/>[SuperDoc.ts]"]
  node_vscode["VS Code editor"]
  node_react["React integration<br/>[SuperDocEditor.tsx]"]
  node_vue["Vue integration<br/>[SuperDocEditor.ts]"]
end

subgraph group_document["Document operations"]
  node_api["Document API<br/>[index.ts]"]
  node_api_types["Document model types<br/>[base.ts]"]
  node_api_validation["Operation validation"]
  node_api_write["Document writes<br/>[write.ts]"]
  node_api_paragraphs["Paragraph operations<br/>[paragraphs.ts]"]
  node_api_query["Document queries<br/>[find.ts]"]
end

subgraph group_engine["DOCX engine"]
  node_docx["OOXML document model<br/>[v2-integration.js]"]
  node_layout["Pagination and layout<br/>[execution.ts]"]
  node_paragraph_layout["Paragraph layout"]
  node_table_layout["Table layout<br/>[layout-table.ts]"]
  node_resolved["Resolved layout<br/>[resolveLayout.ts]"]
  node_painter["Document rendering"]
  node_numbering["List numbering"]
end

subgraph group_experience["Editing experience"]
  node_ui["Editor interface<br/>[surface-manager.js]"]
  node_watermark["Watermark controls"]
end

subgraph group_integration["Automation and collaboration"]
  node_collab["Yjs collaboration<br/>[awareness.ts]"]
  node_automation["Automation clients"]
  node_sdk["Node and Python SDKs"]
  node_cli_mcp["CLI and MCP"]
end

node_user(("Document user"))

node_user -->|"opens or edits"| node_browser
node_user -.->|"edits DOCX"| node_vscode
node_user -.->|"edits DOCX"| node_react
node_user -.->|"edits DOCX"| node_vue
node_browser -->|"uses API"| node_api
node_react -.->|"mounts editor"| node_browser
node_vue -.->|"mounts editor"| node_browser
node_vscode -.->|"hosts editor"| node_browser
node_api -.->|"uses model"| node_api_types
node_api -.->|"validates inputs"| node_api_validation
node_api -.->|"executes writes"| node_api_write
node_api -.->|"dispatches operations"| node_api_paragraphs
node_api -.->|"supports queries"| node_api_query
node_api_write -->|"writes OOXML"| node_docx
node_browser -->|"edits document model"| node_docx
node_docx -.->|"lays out pages"| node_layout
node_layout -->|"lays out paragraphs"| node_paragraph_layout
node_paragraph_layout -->|"lays out tables"| node_table_layout
node_layout -.->|"resolves layout"| node_resolved
node_resolved -.->|"renders content"| node_painter
node_layout -.->|"formats list markers"| node_numbering
node_browser -.->|"presents controls"| node_ui
node_ui -.->|"offers watermark editing"| node_watermark
node_browser -->|"collaborates with Yjs"| node_collab
node_automation -->|"operates documents"| node_api
node_sdk -->|"uses shared API"| node_api
node_cli_mcp -->|"uses shared API"| node_api

click node_browser "https://github.com/superdoc/docx-editor/blob/main/packages/superdoc/src/core/SuperDoc.ts"
click node_vscode "https://github.com/superdoc/docx-editor/blob/main/apps/vscode-ext/src/superdocEditorProvider.ts"
click node_react "https://github.com/superdoc/docx-editor/blob/main/packages/react/src/SuperDocEditor.tsx"
click node_vue "https://github.com/superdoc/docx-editor/blob/main/packages/vue/src/SuperDocEditor.ts"
click node_api "https://github.com/superdoc/docx-editor/blob/main/packages/document-api/src/index.ts"
click node_api_types "https://github.com/superdoc/docx-editor/blob/main/packages/document-api/src/types/base.ts"
click node_api_validation "https://github.com/superdoc/docx-editor/blob/main/packages/document-api/src/validation-primitives.ts"
click node_api_write "https://github.com/superdoc/docx-editor/blob/main/packages/document-api/src/write/write.ts"
click node_api_paragraphs "https://github.com/superdoc/docx-editor/blob/main/packages/document-api/src/paragraphs/paragraphs.ts"
click node_api_query "https://github.com/superdoc/docx-editor/blob/main/packages/document-api/src/find/find.ts"
click node_docx "https://github.com/superdoc/docx-editor/blob/main/packages/superdoc/src/core/v2-integration/v2-integration.js"
click node_layout "https://github.com/superdoc/docx-editor/blob/main/packages/layout-engine/layout-engine/src/execution.ts"
click node_paragraph_layout "https://github.com/superdoc/docx-editor/blob/main/packages/layout-engine/layout-engine/src/layout-paragraph.ts"
click node_table_layout "https://github.com/superdoc/docx-editor/blob/main/packages/layout-engine/layout-engine/src/layout-table.ts"
click node_resolved "https://github.com/superdoc/docx-editor/blob/main/packages/layout-engine/layout-resolved/src/resolveLayout.ts"
click node_painter "https://github.com/superdoc/docx-editor/blob/main/packages/layout-engine/painters/dom/src/paragraph/renderParagraphContent.ts"
click node_numbering "https://github.com/superdoc/docx-editor/blob/main/packages/word-layout/src/numbering-manager.ts"
click node_ui "https://github.com/superdoc/docx-editor/blob/main/packages/superdoc/src/core/surface-manager.js"
click node_watermark "https://github.com/superdoc/docx-editor/blob/main/packages/superdoc/src/public/ui/watermark-controller.ts"
click node_collab "https://github.com/superdoc/docx-editor/blob/main/shared/common/collaboration/awareness.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_browser,node_vscode,node_react,node_vue,node_user toneBlue
class node_api,node_api_types,node_api_validation,node_api_write,node_api_paragraphs,node_api_query toneAmber
class node_docx,node_layout,node_paragraph_layout,node_table_layout,node_resolved,node_painter,node_numbering toneMint
class node_ui,node_watermark toneRose
class node_collab,node_automation,node_sdk,node_cli_mcp toneIndigo
```

## Components

### Editor entry points

- [Browser editor](https://github.com/superdoc/docx-editor/blob/main/packages/superdoc/src/core/SuperDoc.ts): `packages/superdoc/src/core/SuperDoc.ts`
- [VS Code editor](https://github.com/superdoc/docx-editor/blob/main/apps/vscode-ext/src/superdocEditorProvider.ts): `apps/vscode-ext/src/superdocEditorProvider.ts`
- [React integration](https://github.com/superdoc/docx-editor/blob/main/packages/react/src/SuperDocEditor.tsx): `packages/react/src/SuperDocEditor.tsx`
- [Vue integration](https://github.com/superdoc/docx-editor/blob/main/packages/vue/src/SuperDocEditor.ts): `packages/vue/src/SuperDocEditor.ts`

### Document operations

- [Document API](https://github.com/superdoc/docx-editor/blob/main/packages/document-api/src/index.ts): `packages/document-api/src/index.ts`
- [Document model types](https://github.com/superdoc/docx-editor/blob/main/packages/document-api/src/types/base.ts): `packages/document-api/src/types/base.ts`
- [Operation validation](https://github.com/superdoc/docx-editor/blob/main/packages/document-api/src/validation-primitives.ts): `packages/document-api/src/validation-primitives.ts`
- [Document writes](https://github.com/superdoc/docx-editor/blob/main/packages/document-api/src/write/write.ts): `packages/document-api/src/write/write.ts`
- [Paragraph operations](https://github.com/superdoc/docx-editor/blob/main/packages/document-api/src/paragraphs/paragraphs.ts): `packages/document-api/src/paragraphs/paragraphs.ts`
- [Document queries](https://github.com/superdoc/docx-editor/blob/main/packages/document-api/src/find/find.ts): `packages/document-api/src/find/find.ts`

### DOCX engine

- [OOXML document model](https://github.com/superdoc/docx-editor/blob/main/packages/superdoc/src/core/v2-integration/v2-integration.js): `packages/superdoc/src/core/v2-integration/v2-integration.js`
- [Pagination and layout](https://github.com/superdoc/docx-editor/blob/main/packages/layout-engine/layout-engine/src/execution.ts): `packages/layout-engine/layout-engine/src/execution.ts`
- [Paragraph layout](https://github.com/superdoc/docx-editor/blob/main/packages/layout-engine/layout-engine/src/layout-paragraph.ts): `packages/layout-engine/layout-engine/src/layout-paragraph.ts`
- [Table layout](https://github.com/superdoc/docx-editor/blob/main/packages/layout-engine/layout-engine/src/layout-table.ts): `packages/layout-engine/layout-engine/src/layout-table.ts`
- [Resolved layout](https://github.com/superdoc/docx-editor/blob/main/packages/layout-engine/layout-resolved/src/resolveLayout.ts): `packages/layout-engine/layout-resolved/src/resolveLayout.ts`
- [Document rendering](https://github.com/superdoc/docx-editor/blob/main/packages/layout-engine/painters/dom/src/paragraph/renderParagraphContent.ts): `packages/layout-engine/painters/dom/src/paragraph/renderParagraphContent.ts`
- [List numbering](https://github.com/superdoc/docx-editor/blob/main/packages/word-layout/src/numbering-manager.ts): `packages/word-layout/src/numbering-manager.ts`

### Editing experience

- [Editor interface](https://github.com/superdoc/docx-editor/blob/main/packages/superdoc/src/core/surface-manager.js): `packages/superdoc/src/core/surface-manager.js`
- [Watermark controls](https://github.com/superdoc/docx-editor/blob/main/packages/superdoc/src/public/ui/watermark-controller.ts): `packages/superdoc/src/public/ui/watermark-controller.ts`

### Automation and collaboration

- [Yjs collaboration](https://github.com/superdoc/docx-editor/blob/main/shared/common/collaboration/awareness.ts): `shared/common/collaboration/awareness.ts`
- **Automation clients**
- **Node and Python SDKs**
- **CLI and MCP**

### Other components

- **Document user**

## Connections

- Document user → Browser editor: opens or edits (evidence: `README.md`)
- Document user → VS Code editor: edits DOCX
- Document user → React integration: edits DOCX
- Document user → Vue integration: edits DOCX
- Browser editor → Document API: uses API (evidence: `README.md`)
- React integration → Browser editor: mounts editor
- Vue integration → Browser editor: mounts editor
- VS Code editor → Browser editor: hosts editor
- Document API → Document model types: uses model
- Document API → Operation validation: validates inputs
- Document API → Document writes: executes writes
- Document API → Paragraph operations: dispatches operations
- Document API → Document queries: supports queries
- Document writes → OOXML document model: writes OOXML (evidence: `README.md`)
- Browser editor → OOXML document model: edits document model (evidence: `README.md`)
- OOXML document model → Pagination and layout: lays out pages
- Pagination and layout → Paragraph layout: lays out paragraphs (evidence: `packages/layout-engine/layout-engine/src/layout-paragraph.ts`)
- Paragraph layout → Table layout: lays out tables (evidence: `packages/layout-engine/layout-engine/src/layout-paragraph.ts`)
- Pagination and layout → Resolved layout: resolves layout
- Resolved layout → Document rendering: renders content
- Pagination and layout → List numbering: formats list markers
- Browser editor → Editor interface: presents controls
- Editor interface → Watermark controls: offers watermark editing
- Browser editor → Yjs collaboration: collaborates with Yjs (evidence: `README.md`)
- Automation clients → Document API: operates documents (evidence: `README.md`)
- Node and Python SDKs → Document API: uses shared API (evidence: `README.md`)
- CLI and MCP → Document API: uses shared API (evidence: `README.md`)
