# y-js/yjs architecture

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

- Interactive diagram: https://gitdiagram.com/y-js/yjs
- Repository: https://github.com/y-js/yjs

## Overview

##### Project Type and Purpose
- Project Type: This is a JavaScript library (with Node.js support) providing a CRDT framework. It encapsulates a set of shared types (like Maps, Arrays, Text, and XML elements) that allow multiple clients to collaborate in real time without conflicts.
- Purpose: The framework’s primary purpose is to enable collaborative editing by keeping shared documents synchronized across peers while supporting offline editing, undo/redo functionalities, version snapshots, and external provider integrations (e.g., WebSocket, WebRTC, indexeddb, etc.).

##### File Structure
- Top-Level Elements: The project has configuration and build files (package.json, rollup.config.js, tsconfig.json) indicating a bundled library; GitHub workflows for CI/CD; and a test suite (tests directory and test.html) to verify functionality.
- Core Code: Located in the “src” directory:
- The “src/index.js” serves as the main entry point.
- “src/internals.js” likely manages the internal state or low-level operations.
- “src/structs” folder holds various “AbstractStruct” implementations that capture the CRDT data representations (including content types such as ContentBinary, ContentString, etc.).
- “src/types” implements the shared types—like YArray, YMap, YText, and XML types—that users interact with.
- “src/utils” comprises several utility modules (e.g., connectors, update encoders/decoders, event handlers, snapshot management, undo manager, etc.) that support transactions, update propagation, and relative position handling.
- Testing: The “tests” directory covers a suite of unit and compatibility tests which ensure all CRDT components operate as expected.

##### Extract Architectural Insights from the README
- The README makes emphasis on:
- The core CRDT engine (Y.Doc) that holds the shared document state.
- Shared types (Y.Array, Y.Map, Y.Text, and XML nodes) that encapsulate specific behaviors.
- The transaction-based update propagation: every change is wrapped in a transaction and the document can emit update events.
- Integration points for external “providers” that synchronize changes over networks (e.g., y-websocket, y-webrtc) and enhance persistence (e.g., y-indexeddb). While these providers aren’t directly in this repository, they are part of the overall ecosystem.
- Utilities for update encoding/decoding, state vectors, and relative positions to maintain merge operations precisely.

##### Specific Elements
- Clear Labels: Each module or component (e.g., “Y.Doc”, “Shared Types (Y.Array, Y.Text, etc.)”, “Update Encoder/Decoder”, “UndoManager”, “CRDT Structs”, “Utility Modules”) should be clearly labeled.

##### Putting It All Together
- A “CRDT Structs” block (from src/structs) that feeds into the shared types.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core CRDT Engine
    subgraph "Core CRDT Engine"
        DOC["Y.Doc (CRDT Document)"]:::core
        STRUCTS["CRDT Structs"]:::core
        subgraph "Shared Types"
            YARRAY["Y.Array"]:::shared
            YMAP["Y.Map"]:::shared
            YTEXT["Y.Text"]:::shared
            YXMLELEM["YXmlElement"]:::shared
            YXMLFRAG["YXmlFragment"]:::shared
        end
    end

    %% Transaction Layer
    subgraph "Transaction Layer"
        TXMGR["Transaction Manager"]:::transaction
        ENCODER["Update Encoder"]:::transaction
        DECODER["Update Decoder"]:::transaction
        SNAPSHOT["Snapshot"]:::transaction
        RELOSPOS["Relative Position Handling"]:::transaction
    end

    %% Utilities
    subgraph "Utilities"
        UNDOMGR["UndoManager"]:::utility
        EVTHDLR["Event Handler"]:::utility
        CONNECTOR["Connector Interface"]:::utility
        IDGEN["ID Generation"]:::utility
        LOGGING["Logging"]:::utility
    end

    %% External Providers & Testing/Build
    subgraph "External and Testing"
        EXTPROV["External Providers"]:::external
        TESTS["Testing Suite"]:::test
        ROLLUP["rollup.config.js"]:::build
        TSCONFIG["tsconfig.json"]:::build
        PKG["package.json"]:::build
    end

    %% Connections from Transaction Layer to Y.Doc
    TXMGR -->|"transaction_update"| DOC
    ENCODER -->|"encode_update"| DOC
    DECODER -->|"decode_update"| DOC
    SNAPSHOT -->|"snapshot"| DOC
    RELOSPOS -->|"relative_position"| DOC

    %% Connections from Y.Doc to Shared Types
    DOC -->|"register_YArray"| YARRAY
    DOC -->|"register_YMap"| YMAP
    DOC -->|"register_YText"| YTEXT
    DOC -->|"register_YXmlElement"| YXMLELEM
    DOC -->|"register_YXmlFragment"| YXMLFRAG

    %% CRDT Structs provide structure to Shared Types
    STRUCTS -->|"structure_for"| YARRAY
    STRUCTS -->|"structure_for"| YMAP
    STRUCTS -->|"structure_for"| YTEXT
    STRUCTS -->|"structure_for"| YXMLELEM
    STRUCTS -->|"structure_for"| YXMLFRAG

    %% Utilities connections to Y.Doc
    UNDOMGR -->|"undo_redo_event"| DOC
    EVTHDLR -->|"event_handling"| DOC
    CONNECTOR -->|"connectivity"| DOC
    IDGEN -->|"id_generation"| DOC
    LOGGING -->|"logging"| DOC

    %% External Providers connection
    EXTPROV -->|"provider_sync"| DOC

    %% Testing and Build connections
    TESTS -->|"test_suite"| DOC
    ROLLUP -->|"build_config"| DOC
    TSCONFIG -->|"build_config"| DOC
    PKG -->|"build_config"| DOC

    %% Click Events for Core CRDT Engine
    click DOC "https://github.com/y-js/yjs/blob/main/src/utils/Doc.js"
    click STRUCTS "https://github.com/y-js/yjs/tree/main/src/structs"
    click YARRAY "https://github.com/y-js/yjs/blob/main/src/types/YArray.js"
    click YMAP "https://github.com/y-js/yjs/blob/main/src/types/YMap.js"
    click YTEXT "https://github.com/y-js/yjs/blob/main/src/types/YText.js"
    click YXMLELEM "https://github.com/y-js/yjs/blob/main/src/types/YXmlElement.js"
    click YXMLFRAG "https://github.com/y-js/yjs/blob/main/src/types/YXmlFragment.js"

    %% Click Events for Transaction Layer
    click TXMGR "https://github.com/y-js/yjs/blob/main/src/utils/Transaction.js"
    click ENCODER "https://github.com/y-js/yjs/blob/main/src/utils/UpdateEncoder.js"
    click DECODER "https://github.com/y-js/yjs/blob/main/src/utils/UpdateDecoder.js"
    click SNAPSHOT "https://github.com/y-js/yjs/blob/main/src/utils/Snapshot.js"
    click RELOSPOS "https://github.com/y-js/yjs/blob/main/src/utils/RelativePosition.js"

    %% Click Events for Utilities
    click UNDOMGR "https://github.com/y-js/yjs/blob/main/src/utils/UndoManager.js"
    click EVTHDLR "https://github.com/y-js/yjs/blob/main/src/utils/EventHandler.js"
    click CONNECTOR "https://github.com/y-js/yjs/blob/main/src/utils/AbstractConnector.js"
    click IDGEN "https://github.com/y-js/yjs/blob/main/src/utils/ID.js"
    click LOGGING "https://github.com/y-js/yjs/blob/main/src/utils/logging.js"

    %% Click Events for Testing and Build
    click TESTS "https://github.com/y-js/yjs/tree/main/tests"
    click ROLLUP "https://github.com/y-js/yjs/blob/main/rollup.config.js"
    click TSCONFIG "https://github.com/y-js/yjs/blob/main/tsconfig.json"
    click PKG "https://github.com/y-js/yjs/blob/main/package.json"

    %% Styles
    classDef core fill:#a4d3ee,stroke:#333,stroke-width:2px;
    classDef shared fill:#e6e6fa,stroke:#333,stroke-width:2px;
    classDef transaction fill:#ffe4b5,stroke:#333,stroke-width:2px;
    classDef utility fill:#98fb98,stroke:#333,stroke-width:2px;
    classDef external fill:#ffb6c1,stroke:#333,stroke-width:2px;
    classDef test fill:#f0e68c,stroke:#333,stroke-width:2px;
    classDef build fill:#d3d3d3,stroke:#333,stroke-width:2px;
```
