# cp949/geul architecture

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

- Interactive diagram: https://gitdiagram.com/cp949/geul
- Repository: https://github.com/cp949/geul

## Overview

Geul is a block editor built around a persistent JSON document model, with a headless Tiptap-backed controller and React UI. The principal workflow is to initialize a document, edit it through the React bindings and controller, then validate and represent the resulting model; HTML and GFM import/export provide interoperability branches. The graph includes model validation, editor assembly and editing commands, and the documented IO capabilities. Some subsystem links rely on README package-level descriptions because their implementation excerpts were not provided.

Main entry points: [`packages/core/src/editor-controller.ts`](https://github.com/cp949/geul/blob/main/packages/core/src/editor-controller.ts) (Editor controller), [`packages/model/src/types.ts`](https://github.com/cp949/geul/blob/main/packages/model/src/types.ts) (JSON document), [`packages/model/src/document-structure-validation.ts`](https://github.com/cp949/geul/blob/main/packages/model/src/document-structure-validation.ts) (Document validation), [`packages/core/src/production-editor-session.ts`](https://github.com/cp949/geul/blob/main/packages/core/src/production-editor-session.ts) (Editor session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Document model"]
  node_json_doc["JSON document<br/>[types.ts]"]
  node_model_validation["Document validation"]
  node_block_schema["Block schemas<br/>[block-schema.ts]"]
  node_table_validation["Table grid validation"]
end

subgraph group_core["Headless editor"]
  node_controller["Editor controller"]
  node_session["Editor session"]
  node_assembly["Editor assembly"]
  node_model_projection["Model projection<br/>[model-to-tiptap.ts]"]
  node_block_commands["Block commands"]
  node_media_upload["Media upload<br/>[media-upload.ts]"]
end

subgraph group_react["React interface"]
  node_react_provider["Editor provider"]
  node_editor_content["Editor content<br/>[editor-content.tsx]"]
  node_react_tools["Editing UI"]
  node_media_tools["Media toolbar<br/>[media-toolbar.tsx]"]
end

subgraph group_io["Document interchange"]
  node_markdown_import["Markdown import<br/>[import-markdown.ts]"]
  node_html_import["HTML import<br/>[import-html.ts]"]
  node_clipboard_parse["Clipboard parsing"]
  node_html_export["HTML export<br/>[export-html.ts]"]
  node_markdown_export["Markdown export<br/>[export-markdown.ts]"]
end

node_author(("Editor user"))

node_author -->|"edits with"| node_react_provider
node_react_provider -.->|"renders"| node_editor_content
node_react_provider -->|"binds to"| node_controller
node_react_tools -.->|"issues commands"| node_controller
node_media_tools -.->|"issues commands"| node_controller
node_controller -->|"creates"| node_session
node_controller -->|"creates"| node_block_commands
node_controller -->|"uses"| node_model_projection
node_session -.->|"assembles"| node_assembly
node_session -.->|"projects model"| node_model_projection
node_controller -.->|"supports upload"| node_media_upload
node_json_doc -->|"validated by"| node_model_validation
node_model_validation -->|"checks blocks"| node_block_schema
node_model_validation -.->|"checks tables"| node_table_validation
node_controller -->|"updates document"| node_json_doc
node_markdown_import -->|"imports to"| node_json_doc
node_html_import -->|"imports to"| node_json_doc
node_clipboard_parse -.->|"parses clipboard"| node_json_doc
node_json_doc -->|"exports as HTML"| node_html_export
node_json_doc -->|"exports as GFM"| node_markdown_export

click node_json_doc "https://github.com/cp949/geul/blob/main/packages/model/src/types.ts"
click node_model_validation "https://github.com/cp949/geul/blob/main/packages/model/src/document-structure-validation.ts"
click node_block_schema "https://github.com/cp949/geul/blob/main/packages/model/src/block-schema.ts"
click node_table_validation "https://github.com/cp949/geul/blob/main/packages/model/src/table-grid-validation.ts"
click node_react_provider "https://github.com/cp949/geul/blob/main/packages/react/src/editor-provider.tsx"
click node_editor_content "https://github.com/cp949/geul/blob/main/packages/react/src/editor-content.tsx"
click node_react_tools "https://github.com/cp949/geul/blob/main/packages/react/src/formatting-toolbar.tsx"
click node_media_tools "https://github.com/cp949/geul/blob/main/packages/react/src/media-toolbar.tsx"
click node_controller "https://github.com/cp949/geul/blob/main/packages/core/src/editor-controller.ts"
click node_session "https://github.com/cp949/geul/blob/main/packages/core/src/production-editor-session.ts"
click node_assembly "https://github.com/cp949/geul/blob/main/packages/core/src/production-editor-assembly.ts"
click node_model_projection "https://github.com/cp949/geul/blob/main/packages/core/src/model-to-tiptap.ts"
click node_block_commands "https://github.com/cp949/geul/blob/main/packages/core/src/generic-block-commands.ts"
click node_media_upload "https://github.com/cp949/geul/blob/main/packages/core/src/media-upload.ts"
click node_markdown_import "https://github.com/cp949/geul/blob/main/packages/io/src/markdown/import-markdown.ts"
click node_html_import "https://github.com/cp949/geul/blob/main/packages/io/src/html/import-html.ts"
click node_clipboard_parse "https://github.com/cp949/geul/blob/main/packages/io/src/clipboard/clipboard-table-parser.ts"
click node_html_export "https://github.com/cp949/geul/blob/main/packages/io/src/html/export-html.ts"
click node_markdown_export "https://github.com/cp949/geul/blob/main/packages/io/src/markdown/export-markdown.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_json_doc,node_model_validation,node_block_schema,node_table_validation,node_author toneBlue
class node_controller,node_session,node_assembly,node_model_projection,node_block_commands,node_media_upload toneAmber
class node_react_provider,node_editor_content,node_react_tools,node_media_tools toneMint
class node_markdown_import,node_html_import,node_clipboard_parse,node_html_export,node_markdown_export toneRose
```

## Components

### Document model

- [JSON document](https://github.com/cp949/geul/blob/main/packages/model/src/types.ts): `packages/model/src/types.ts`
- [Document validation](https://github.com/cp949/geul/blob/main/packages/model/src/document-structure-validation.ts): `packages/model/src/document-structure-validation.ts`
- [Block schemas](https://github.com/cp949/geul/blob/main/packages/model/src/block-schema.ts): `packages/model/src/block-schema.ts`
- [Table grid validation](https://github.com/cp949/geul/blob/main/packages/model/src/table-grid-validation.ts): `packages/model/src/table-grid-validation.ts`

### Headless editor

- [Editor controller](https://github.com/cp949/geul/blob/main/packages/core/src/editor-controller.ts): `packages/core/src/editor-controller.ts`
- [Editor session](https://github.com/cp949/geul/blob/main/packages/core/src/production-editor-session.ts): `packages/core/src/production-editor-session.ts`
- [Editor assembly](https://github.com/cp949/geul/blob/main/packages/core/src/production-editor-assembly.ts): `packages/core/src/production-editor-assembly.ts`
- [Model projection](https://github.com/cp949/geul/blob/main/packages/core/src/model-to-tiptap.ts): `packages/core/src/model-to-tiptap.ts`
- [Block commands](https://github.com/cp949/geul/blob/main/packages/core/src/generic-block-commands.ts): `packages/core/src/generic-block-commands.ts`
- [Media upload](https://github.com/cp949/geul/blob/main/packages/core/src/media-upload.ts): `packages/core/src/media-upload.ts`

### React interface

- [Editor provider](https://github.com/cp949/geul/blob/main/packages/react/src/editor-provider.tsx): `packages/react/src/editor-provider.tsx`
- [Editor content](https://github.com/cp949/geul/blob/main/packages/react/src/editor-content.tsx): `packages/react/src/editor-content.tsx`
- [Editing UI](https://github.com/cp949/geul/blob/main/packages/react/src/formatting-toolbar.tsx): `packages/react/src/formatting-toolbar.tsx`
- [Media toolbar](https://github.com/cp949/geul/blob/main/packages/react/src/media-toolbar.tsx): `packages/react/src/media-toolbar.tsx`

### Document interchange

- [Markdown import](https://github.com/cp949/geul/blob/main/packages/io/src/markdown/import-markdown.ts): `packages/io/src/markdown/import-markdown.ts`
- [HTML import](https://github.com/cp949/geul/blob/main/packages/io/src/html/import-html.ts): `packages/io/src/html/import-html.ts`
- [Clipboard parsing](https://github.com/cp949/geul/blob/main/packages/io/src/clipboard/clipboard-table-parser.ts): `packages/io/src/clipboard/clipboard-table-parser.ts`
- [HTML export](https://github.com/cp949/geul/blob/main/packages/io/src/html/export-html.ts): `packages/io/src/html/export-html.ts`
- [Markdown export](https://github.com/cp949/geul/blob/main/packages/io/src/markdown/export-markdown.ts): `packages/io/src/markdown/export-markdown.ts`

### Other components

- **Editor user**

## Connections

- Editor user → Editor provider: edits with (evidence: `README.md`)
- Editor provider → Editor content: renders
- Editor provider → Editor controller: binds to (evidence: `README.md`)
- Editing UI → Editor controller: issues commands
- Media toolbar → Editor controller: issues commands
- Editor controller → Editor session: creates (evidence: `packages/core/src/editor-controller.ts`)
- Editor controller → Block commands: creates (evidence: `packages/core/src/editor-controller.ts`)
- Editor controller → Model projection: uses (evidence: `packages/core/src/editor-controller.ts`)
- Editor session → Editor assembly: assembles
- Editor session → Model projection: projects model
- Editor controller → Media upload: supports upload
- JSON document → Document validation: validated by (evidence: `packages/model/src/document-structure-validation.ts`)
- Document validation → Block schemas: checks blocks (evidence: `packages/model/src/document-structure-validation.ts`)
- Document validation → Table grid validation: checks tables
- Editor controller → JSON document: updates document (evidence: `README.md`)
- Markdown import → JSON document: imports to (evidence: `README.md`)
- HTML import → JSON document: imports to (evidence: `README.md`)
- Clipboard parsing → JSON document: parses clipboard
- JSON document → HTML export: exports as HTML (evidence: `README.md`)
- JSON document → Markdown export: exports as GFM (evidence: `README.md`)
