# loro-dev/loro architecture

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

- Interactive diagram: https://gitdiagram.com/loro-dev/loro
- Repository: https://github.com/loro-dev/loro

## Overview

##### Main Components

a) Core Components:
- CRDT Engine (loro-internal)
- Data Containers (Text, Tree, List, Map)
- Version Control System
- Synchronization Layer
- Storage Layer (KV Store)

b) Integration Layers:
- FFI Layer (loro-ffi)
- WASM Bindings (loro-wasm)
- Language-specific APIs

##### Architecture Patterns to Highlight

- Modular architecture with clear separation of concerns
- Data flow patterns for synchronization
- Version control mechanisms
- Plugin-based container system

**┌─ Client Applications ─────────────────────┐**
- JavaScript/Rust/Swift Applications      │
- ┬─────────────────────┘
- ↓
**┌─ Integration Layer ────────────────────────┐**
- ┌─────────────┐  ┌──────────┐  ┌───────┐ │
- loro-wasm  │  │ loro-ffi │  │ loro  │ │
- ┘  └──────────┘  └───────┘ │
- ┬─────────────────────┘
- ↓
**┌─ Core Engine (loro-internal) ─────────────┐**
- ┌─────────────┐ ┌──────────┐ ┌─────────┐ │
- CRDT Engine  │ │Version   │ │Delta    │ │
- Control   │ │Handling │ │
- ┘ └──────────┘ └─────────┘ │
- ┌─────────────┐ ┌──────────┐ ┌─────────┐ │
- Containers   │ │Event     │ │State    │ │
- Management  │ │System    │ │Manager  │ │
- ┘ └──────────┘ └─────────┘ │
- ┬─────────────────────┘
- ↓
**┌─ Storage Layer ───────────────────────────┐**
- ┌─────────────┐    ┌─────────────────┐  │
- KV Store   │    │ Change Store    │  │
- ┘    └─────────────────┘  │
- ┘

##### Key Relationships

- Bidirectional sync between clients
- Delta propagation paths
- Version control branching
- Container type inheritance
- Event flow patterns

##### Implementation Details to Note

- The modular crate structure
- WASM bridge architecture
- FFI interface points
- Storage abstraction layer
- Container type system

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client["Client Applications"]
        JS[JavaScript Apps]
        Rust[Rust Apps]
        Swift[Swift Apps]
    end

    subgraph Integration["Integration Layer"]
        WASM["WASM Bindings"]:::wasm
        FFI["FFI Interface"]:::ffi
        API["Loro API"]:::api
    end

    subgraph Core["Core Engine"]
        Engine["CRDT Engine"]:::engine
        
        subgraph Containers["Data Containers"]
            Text["Text Container"]:::container
            Tree["Tree Container"]:::container
            List["List Container"]:::container
            Map["Map Container"]:::container
        end
        
        Version["Version Control"]:::version
        Delta["Delta Handling"]:::delta
        Sync["Synchronization"]:::sync
        State["State Manager"]:::state
        Event["Event System"]:::event
        Change["Change Management"]:::change
        Encoding["Encoding Layer"]:::encoding
        Utils["Common Utilities"]:::utils
    end

    subgraph Storage["Storage Layer"]
        KV["KV Store"]:::storage
        ChangeStore["Change Store"]:::storage
    end

    %% Relationships
    JS & Rust & Swift --> WASM & FFI
    WASM & FFI --> API
    API --> Engine
    
    Engine --> Containers
    Engine --> Version
    Engine --> Delta
    Engine --> Sync
    Engine --> State
    Engine --> Event
    Engine --> Change
    Engine --> Encoding
    
    State --> KV
    Change --> ChangeStore
    
    %% Styles
    classDef container fill:#a8d08d
    classDef engine fill:#4472c4
    classDef storage fill:#ffc000
    classDef version fill:#70ad47
    classDef delta fill:#ed7d31
    classDef sync fill:#7030a0
    classDef state fill:#4472c4
    classDef event fill:#833c0c
    classDef change fill:#548235
    classDef encoding fill:#c65911
    classDef utils fill:#808080
    classDef wasm fill:#2f5597
    classDef ffi fill:#5b9bd5
    classDef api fill:#70ad47

    %% Click Events
    click Engine "https://github.com/loro-dev/loro/blob/main/crates/loro-internal/src/loro.rs"
    click Text "https://github.com/loro-dev/loro/tree/main/crates/loro-internal/src/container/richtext/"
    click Tree "https://github.com/loro-dev/loro/tree/main/crates/loro-internal/src/container/tree/"
    click List "https://github.com/loro-dev/loro/tree/main/crates/loro-internal/src/container/list/"
    click Map "https://github.com/loro-dev/loro/tree/main/crates/loro-internal/src/container/map/"
    click Version "https://github.com/loro-dev/loro/tree/main/crates/loro-internal/src/version/"
    click KV "https://github.com/loro-dev/loro/tree/main/crates/kv-store/src/"
    click FFI "https://github.com/loro-dev/loro/tree/main/crates/loro-ffi/src/"
    click WASM "https://github.com/loro-dev/loro/tree/main/crates/loro-wasm/src/"
    click Delta "https://github.com/loro-dev/loro/tree/main/crates/delta/src/"
    click Sync "https://github.com/loro-dev/loro/tree/main/crates/loro-internal/src/oplog/"
    click State "https://github.com/loro-dev/loro/tree/main/crates/loro-internal/src/state/"
    click Event "https://github.com/loro-dev/loro/blob/main/crates/loro-internal/src/event.rs"
    click Change "https://github.com/loro-dev/loro/blob/main/crates/loro-internal/src/change.rs"
    click Encoding "https://github.com/loro-dev/loro/tree/main/crates/loro-internal/src/encoding/"
    click Utils "https://github.com/loro-dev/loro/tree/main/crates/loro-common/src/"
```
