# prosemirror/prosemirror-model architecture

> Architecture diagram of the GitHub repository prosemirror/prosemirror-model, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prosemirror/prosemirror-model
- Repository: https://github.com/prosemirror/prosemirror-model

## Overview

##### Project Type and Purpose
- This is an open-source library module (“prosemirror-model”) that implements the core document model for the ProseMirror rich-text editor.
- Its role is purely “model”-level: defining schemas, node/fragment trees, marks, content constraints, position resolution, and conversion to/from DOM.

##### File Structure
- Top level:
- package.json, config files, README/CONTRIBUTING/CHANGELOG – standard npm module metadata
- /src – TypeScript source files, each implementing a distinct part of the model
- /test – unit tests exercising each module
- schema.ts – defines Schema, NodeType, MarkType
- node.ts – Node class, tree structure API
- fragment.ts – Fragment class, a sequence of Nodes
- content.ts – ContentMatch, parsing content constraints
- resolvedpos.ts – ResolvedPos, tree position utilities
- .ts – Mark class, attaching metadata to nodes
- dom.ts / from_dom.ts / to_dom.ts – DOMSerializer, DOMParser, conversion logic
- diff.ts / comparedeep.ts – tree diffing algorithms
- replace.ts – content replacement transformations
- index.ts – module barrel exporting all public APIs

##### README for Additional Insights
- Confirms this is a “core module” used by ProseMirror’s higher-level editing engine.
- No external services or network layers—pure in-memory model and DOM I/O.

- Schema Layer (schema.ts)
- Node/Fragment Layer (node.ts, fragment.ts)
- Layer (mark.ts)
- Content Validation (content.ts)
- Utilities (resolvedpos.ts)
- Transformation/Replacement (replace.ts)
- Diffing Engine (diff.ts, comparedeep.ts)
- DOM Conversion (dom.ts, from_dom.ts, to_dom.ts)

b. Relationships and Interactions:
- Schema defines NodeType/MarkType → used by Node, Mark, Fragment to enforce structure.
- Node contains zero or more child Fragments; Fragment is a sequence of Nodes.
- ContentMatch validates which child nodes are permitted by Schema.
- ResolvedPos takes a Node tree and an offset → produces path info for positions.
- Marks attach to Nodes as metadata; Marks are validated against Schema.
- replace.ts uses Node/Fragment APIs to perform tree manipulations.
- diff.ts compares two Node trees via comparedeep() → outputs minimal change steps.
- dom.ts/from_dom.ts convert between Node trees and browser DOM.

c. Architectural Patterns / Design Principles:
- Modular single-responsibility components (one file = one conceptual module).
- Immutable tree data structures (Nodes, Fragments).
- Separation of concerns: model vs. serializer vs. diff/transform.

d. Key Technologies / Libraries:
- TypeScript for type safety
- Standard DOM APIs for serialization/parsing
- No external databases or network

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% I/O Layer
    subgraph "I/O Layer"
        DOMHelpers["dom.ts: DOMSerializer Helpers"]:::io
        DOMParser["from_dom.ts: DOMParser"]:::io
        DOMSerializer["to_dom.ts: DOMSerializer"]:::io
    end

    %% Core Model Layer
    subgraph "Core Model Layer"
        Schema["schema.ts: Schema"]:::core
        Node["node.ts: Node"]:::core
        Fragment["fragment.ts: Fragment"]:::core
        Mark["mark.ts: Mark"]:::core
    end

    %% Public API
    Index["index.ts: Public API"]:::api

    %% Utilities Layer
    subgraph "Utilities & Transform"
        Content["content.ts: ContentMatch"]:::utils
        ResolvedPos["resolvedpos.ts: ResolvedPos"]:::utils
        Replace["replace.ts: replace"]:::transform
        Diff["diff.ts: diff"]:::transform
        CompareDeep["comparedeep.ts: comparedeep"]:::transform
    end

    %% Relationships
    Schema -->|defines types for| Node
    Schema -->|defines types for| Fragment
    Schema -->|defines types for| Mark

    Node -->|contains children sequence| Fragment
    Fragment -->|composed of| Node

    Content -->|validates child nodes for| Node
    Content -->|validates child fragments for| Fragment
    Content -->|validates marks for| Mark

    ResolvedPos -->|queries positions in| Node

    Mark -->|attaches metadata to| Node

    Replace -->|transforms| Node
    Replace -->|transforms| Fragment

    Node -->|input trees| CompareDeep
    Node -->|input trees| Diff
    CompareDeep -->|provides deep compare to| Diff

    DOMHelpers -->|used by| DOMParser
    DOMHelpers -->|used by| DOMSerializer

    DOMParser -->|parses DOM to| Node
    Node -->|serializes to DOM via| DOMSerializer

    %% Public API connections
    Index --> Schema
    Index --> Node
    Index --> Fragment
    Index --> Mark
    Index --> Content
    Index --> ResolvedPos
    Index --> Replace
    Index --> Diff
    Index --> CompareDeep
    Index --> DOMParser
    Index --> DOMSerializer

    %% Click Events
    click Schema "https://github.com/prosemirror/prosemirror-model/blob/master/src/schema.ts"
    click Node "https://github.com/prosemirror/prosemirror-model/blob/master/src/node.ts"
    click Fragment "https://github.com/prosemirror/prosemirror-model/blob/master/src/fragment.ts"
    click Mark "https://github.com/prosemirror/prosemirror-model/blob/master/src/mark.ts"
    click Content "https://github.com/prosemirror/prosemirror-model/blob/master/src/content.ts"
    click ResolvedPos "https://github.com/prosemirror/prosemirror-model/blob/master/src/resolvedpos.ts"
    click Replace "https://github.com/prosemirror/prosemirror-model/blob/master/src/replace.ts"
    click Diff "https://github.com/prosemirror/prosemirror-model/blob/master/src/diff.ts"
    click CompareDeep "https://github.com/prosemirror/prosemirror-model/blob/master/src/comparedeep.ts"
    click DOMHelpers "https://github.com/prosemirror/prosemirror-model/blob/master/src/dom.ts"
    click DOMParser "https://github.com/prosemirror/prosemirror-model/blob/master/src/from_dom.ts"
    click DOMSerializer "https://github.com/prosemirror/prosemirror-model/blob/master/src/to_dom.ts"
    click Index "https://github.com/prosemirror/prosemirror-model/blob/master/src/index.ts"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef utils fill:#90EE90,stroke:#333,stroke-width:1px
    classDef transform fill:#FFA500,stroke:#333,stroke-width:1px
    classDef io fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef api fill:#D3D3D3,stroke:#333,stroke-width:1px
```
