# muni-town/leaf architecture

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

- Interactive diagram: https://gitdiagram.com/muni-town/leaf
- Repository: https://github.com/muni-town/leaf

## Overview

##### Main Components
- Core API / SDK (src/index.ts and related utility functions): This is the heart of Leaf SDK that ties together CRDT functionality.
- Storage Abstraction Layer (src/storage folder): Contains multiple implementations for local persistence and retrieval. Notice the modules such as deno-fs, deno-kv, and indexed-db. This layer ensures that storage choices can be switched or extended.
- Synchronization Module (src/sync1 folder): Contains protocol definitions (proto.ts) plus WebSocket client and server implementations (ws-client.ts and ws-server.ts) to enable peer-to-peer or client-server synchronization using CRDTs.
- Framework / UI Integration Module: The svelte.ts file indicates integration with Svelte, which helps frontend applications easily bind to the SDK.
- Examples & Documentation: The examples folder and the docs folder (with typedoc configuration) demonstrate usage and provide API documentation. Although not runtime components, they are essential for understanding how to integrate and extend the system.

##### Out Relationships and Data Flows
- The Core API ties directly to:
- The Storage Abstraction Layer for handling local data persistence.
- The Synchronization Module for keeping state consistent across peers or over network boundaries.
- The Svelte integration layer that lets UI components react to state changes.
- In the synchronization part, the WebSocket client and server components communicate with each other to propagate CRDT state across instances.
- The Core API is the hub – all external application layers (e.g., Svelte-based UIs or other frontend components) interact with it.

##### Architectural Patterns and Key Design Principles
- Abstraction and Adapter Pattern: The multiple storage options (Deno’s filesystem, KV storage, IndexedDB) suggest an abstraction layer that can adapt to different backends. Represent this as interchangeable storage adapter components.
- Modular Design: Separate modules for storage, synchronization, and integration show a clear separation of concerns.
- Local-First Philosophy: Emphasize that the design is tailored for offline-first or local-first applications, and the synchronization module is built to reconcile changes in a distributed environment.

##### Relevant Technologies, Frameworks, and Tools
- Deno Ecosystem: With files like deno.lock and tsconfig files, it’s clear that the project is built on Deno.
- CRDT Tools: Although not explicitly detailed in the file names, the core purpose implies underlying CRDT operations.
- WebSocket for real-time communication (ws-client.ts, ws-server.ts).
- Svelte: The svelte.ts file indicates a tight coupling for UI integration.
- TypeDoc: The extensive docs folder pointing to typedoc configurations shows automated documentation generation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Application
    app("External Application"):::external

    %% Core API / SDK
    subgraph "Core API / SDK"
        core("Core API"):::sdk
        utils("Utils"):::sdk
    end

    %% Storage Abstraction Layer
    subgraph "Storage Abstraction Layer"
        fs("deno-fs"):::storage
        kv("deno-kv"):::storage
        indexed("indexed-db"):::storage
    end

    %% Synchronization Module
    subgraph "Synchronization Module"
        proto("Protocol Definitions"):::sync
        wsClient("WebSocket Client"):::sync
        wsServer("WebSocket Server"):::sync
        mainSync("Main Sync Module"):::sync
    end

    %% Svelte Integration Module
    svelte("Svelte Integration"):::integration

    %% Examples & Documentation
    subgraph "Examples & Documentation"
        examples("Examples"):::docs
        docs("Docs"):::docs
    end

    %% Relationships
    app -->|"calls"| core
    core -->|"uses"| utils
    core -->|"stores data via"| fs
    core -->|"stores data via"| kv
    core -->|"stores data via"| indexed
    core -->|"syncs via"| mainSync
    mainSync -->|"defines"| proto
    mainSync -->|"communicates"| wsClient
    mainSync -->|"communicates"| wsServer
    wsClient <-->|"communicates"| wsServer
    core -->|"integrates"| svelte

    %% External docs connection
    app -->|"references"| examples
    app -->|"references"| docs

    %% Click Events
    click core "https://github.com/muni-town/leaf/blob/main/src/index.ts"
    click utils "https://github.com/muni-town/leaf/blob/main/src/utils.ts"
    click fs "https://github.com/muni-town/leaf/blob/main/src/storage/deno-fs.ts"
    click kv "https://github.com/muni-town/leaf/blob/main/src/storage/deno-kv.ts"
    click indexed "https://github.com/muni-town/leaf/blob/main/src/storage/indexed-db.ts"
    click mainSync "https://github.com/muni-town/leaf/blob/main/src/sync1.ts"
    click proto "https://github.com/muni-town/leaf/blob/main/src/sync1/proto.ts"
    click wsClient "https://github.com/muni-town/leaf/blob/main/src/sync1/ws-client.ts"
    click wsServer "https://github.com/muni-town/leaf/blob/main/src/sync1/ws-server.ts"
    click svelte "https://github.com/muni-town/leaf/blob/main/src/svelte.ts"
    click examples "https://github.com/muni-town/leaf/tree/main/examples"
    click docs "https://github.com/muni-town/leaf/tree/main/docs"

    %% Styles
    classDef sdk fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef storage fill:#ffe082,stroke:#ff6f00,stroke-width:2px;
    classDef sync fill:#c8e6c9,stroke:#1b5e20,stroke-width:2px;
    classDef integration fill:#d1c4e9,stroke:#4a148c,stroke-width:2px;
    classDef docs fill:#ffd54f,stroke:#ff6f00,stroke-width:2px;
    classDef external fill:#e1bee7,stroke:#6a1b9a,stroke-width:2px;
```
