# mweiss/elm-rte-toolkit architecture

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

- Interactive diagram: https://gitdiagram.com/mweiss/elm-rte-toolkit
- Repository: https://github.com/mweiss/elm-rte-toolkit

## Overview

##### Project type and purpose
- This is an open-source Elm library/toolkit (“Rich Text Editor Toolkit”) plus a demo application.
- The library provides a programmable specification, commands, model, and view logic for building cross-platform rich-text editors in Elm.
- The demo folder is a standalone Create-Elm-App project that exercises the library as a WebComponent.

##### File structure
- Top-level folders and files:
- src/RichText – all Elm modules that make up the library:
– Config (spec, commands, decorations, element/mark definitions)
– Model (state, node, inline element, history, selection, etc.)
– Commands (insert, delete, wrap, lift, etc.)
– Html renderer
– Internal modules (DOM integration, events, history management, mutation observers)
– Editor entry point and Node abstraction
- demo – example app that imports and uses the compiled library as an ES6 web component
– elm.json, package.json, public/index.html, CSS, Elm sources (Main.elm orchestrating pages, routes, editor instance)
– js/elmEditor.js – compiled JS wrapper exporting the Elm editor as a custom element
– build/test scripts (build.sh, elm-app start, elm-test)
- js/elmEditor.js – the library’s pre-compiled WebComponent wrapper for non-bundler usage
- publish.sh – script to publish the package

##### README for additional insights
- Confirms that js/elmEditor.js + webcomponents polyfill turn the Elm editor into a custom element
- Demo is bootstrapped with Create-Elm-App; tests live in demo/tests
- Emphasis on using browser events and mutation observers to detect editor changes

a. Main components
- Browser environment
– WebComponents polyfill (optional)
– Custom Element (<elm-editor>) from js/elmEditor.js
- Elm compiled code
– Entry point: RichText.Editor
– Core subsystems in Elm:
· Config & Spec (drives allowed document structure)
· Model (document state, selection, history)
· Commands (user-driven transformations)
· Html Renderer (Virtual DOM ↔ real DOM)
· Internal integration (BeforeInput, keydown, paste, mutation observers)
- Demo application (Create-Elm-App)
– Elm Main app orchestrating pages, routes, editor instances
– Static assets (CSS, index.html)
- Build & Test Tools
– elm-app, elm-test, build.sh, publish.sh

b. Relationships & interactions
1. User interacts with the editor in the page (click, keypress, paste)
2. Browser fires DOM events → WebComponent wrapper captures events → forwards to Elm (ports or direct message)
3. Elm Editor module invokes Internal event handlers → translates to Commands → updates Model
4. Model change triggers Html Renderer → Virtual DOM diff → actual DOM updates inside the custom element
5. Mutation observers detect contenteditable mutations → feed back into Elm for consistency
6. Demo app uses the custom element API to instantiate/configure the editor with a Spec

c. Architectural patterns & design principles
- Modular Elm code split by concern (Config, Model, Commands, Renderer, Internals)
- Functional core with immutable Model, pure Command transformations
- Event-driven architecture bridging browser I/O and functional update loop
- WebComponent boundary isolates editor implementation from host page

d. Key technologies & libraries
- Elm (0.19) for core logic
- WebComponents (custom-elements, optional polyfills)
- create-elm-app for demo
- MutationObserver API, contenteditable for I/O
- CSS for styling the editor container

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Browser Environment"
        Polyfills["WebComponents Polyfill"]:::browser
        BrowserEnv["Browser (Events, DOM, MutationObserver)"]:::browser
    end

    subgraph "WebComponent Wrapper"
        EditorWrapper["<elm-editor> WebComponent"]:::wrapper
    end

    subgraph "Elm Core Library"
        EditorEntry["RichText.Editor (Entry Point)"]:::elm
        Config["Config & Spec"]:::elm
        Model["Model"]:::elm
        Commands["Commands"]:::elm
        Renderer["Html Renderer"]:::elm
        Internals["Internal Integrations"]:::elm
        NodeAbstraction["Node Abstraction"]:::elm
        ListUtils["List Utilities"]:::elm
    end

    subgraph "Demo Application"
        DemoApp["Demo (Create-Elm-App)"]:::demo
    end

    subgraph "Build & Test Tools"
        ElmApp["elm-app, elm-test"]:::tool
        Scripts["build.sh, publish.sh"]:::tool
    end

    Polyfills --> BrowserEnv
    BrowserEnv -->|"Custom Element API"| EditorWrapper
    EditorWrapper -->|"Initializes"| EditorEntry

    EditorEntry --> Config
    EditorEntry --> Model
    EditorEntry --> Commands
    EditorEntry --> Renderer
    EditorEntry --> Internals
    EditorEntry --> NodeAbstraction
    EditorEntry --> ListUtils

    Commands --> Model
    Model --> Renderer
    Renderer -->|"Virtual DOM diff"| BrowserEnv
    BrowserEnv -->|"MutationObserver callbacks"| Internals
    Internals -->|"DOM events"| EditorEntry

    DemoApp -->|"Uses Custom Element"| BrowserEnv
    DemoApp --> ElmApp
    ElmApp --> Scripts

    click Config "https://github.com/mweiss/elm-rte-toolkit/tree/master/src/RichText/Config"
    click Model "https://github.com/mweiss/elm-rte-toolkit/tree/master/src/RichText/Model"
    click Commands "https://github.com/mweiss/elm-rte-toolkit/blob/master/src/RichText/Commands.elm"
    click Renderer "https://github.com/mweiss/elm-rte-toolkit/blob/master/src/RichText/Html.elm"
    click Internals "https://github.com/mweiss/elm-rte-toolkit/tree/master/src/RichText/Internal"
    click EditorEntry "https://github.com/mweiss/elm-rte-toolkit/blob/master/src/RichText/Editor.elm"
    click NodeAbstraction "https://github.com/mweiss/elm-rte-toolkit/blob/master/src/RichText/Node.elm"
    click ListUtils "https://github.com/mweiss/elm-rte-toolkit/blob/master/src/RichText/List.elm"
    click EditorWrapper "https://github.com/mweiss/elm-rte-toolkit/blob/master/js/elmEditor.js"
    click DemoApp "https://github.com/mweiss/elm-rte-toolkit/tree/master/demo"
    click ElmApp "https://github.com/mweiss/elm-rte-toolkit/blob/master/demo/build.sh"
    click Scripts "https://github.com/mweiss/elm-rte-toolkit/blob/master/publish.sh"

    classDef elm fill:#cce5ff,stroke:#004085,color:#004085
    classDef wrapper fill:#d4edda,stroke:#155724,color:#155724
    classDef browser fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef demo fill:#fff3cd,stroke:#856404,color:#856404
    classDef tool fill:#f8d7da,stroke:#721c24,color:#721c24
```
