# lordmendes/liquidbrain architecture

> Architecture diagram of the GitHub repository lordmendes/liquidbrain, 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/lordmendes/liquidbrain
- Repository: https://github.com/lordmendes/liquidbrain

## Overview

##### Project type and purpose
- LiquidBrain is an open-source, framework-agnostic JavaScript/TypeScript library (packaged via npm and UMD) that provides autocomplete suggestions for `<input>`, `<textarea>`, and `contenteditable` elements.
- It exposes two main classes—LiquidBrainEngine (business logic) and LiquidBrainUI (DOM/UI integration)—and ships with styles (CSS) plus a UMD build for direct browser use.

##### File structure
- Top-level files:
- package.json, tsconfig.json, rollup.config.cjs — configuration for package metadata, TypeScript compiler, and bundling.
- readme.md — project documentation.
- .gitignore — VCS ignores.
- Examples/vanilla+html — demo of UMD build usage.
- src/ directory:
- LiquidBrainEngine.ts — core suggestion engine.
- LiquidBrainUI.ts — UI integration layer (event listeners, modal management).
- index.ts — public API exports.
- types.ts — shared type definitions.
- liquidbrain.css — default styling.
- build artifacts (not shown) are generated via Rollup according to rollup.config.cjs.

##### README for architectural insights
- The README describes separation of concerns: Engine handles data-model parsing, suggestion fetching, insertion logic; UI handles DOM attachment, rendering suggestions, and user interaction.
- It highlights optional custom rendering and customizable markers.

a. Main components:
1. Consumer Application — any web page or framework using LiquidBrain.
2. LiquidBrainUI (Browser/UI layer) — attaches to an input element, listens for keystrokes, triggers engine calls, and renders suggestion modal.
3. LiquidBrainEngine (Logic layer) — processes the data model, resolves nested properties, returns suggestion list, and computes insertion.
4. Data Model — JSON or JS object provided by the consumer describing suggestion hierarchy.
5. CSS Styles — default `.liquidbrain-modal`, `.liquidbrain-suggestion-item`, etc.
6. Bundler / Build Pipeline — Rollup + TypeScript, produces ESM, CJS, and UMD artifacts.
7. npm Registry / Direct Download — distribution endpoints.
b. Relationships and data flow:
- Consumer App → (init) → LiquidBrainUI: passes model, inputElement, markers, optional customRenderer.
- LiquidBrainUI → (on keystroke) → LiquidBrainEngine.handleFetchSuggestionsFromValue(value, cursor).
- LiquidBrainEngine → (suggestions) → LiquidBrainUI → (render) → DOM modal styled by CSS.
- UI → (on suggestion select) → Engine.insertSuggestion → UI updates input value and cursor.
- Bundler takes src/ → compiles/transpiles TS → outputs dist/ (ESM/CJS/UMD) → published to npm or distributed via direct download.
c. Architectural patterns and principles:
- Separation of concerns: UI vs. logic.
- Publish-subscribe callbacks for value changes and suggestions.
- Plugin-style extensibility: custom renderer hook.
- Framework-agnostic design promotes portability.
d. Relevant technologies:
- TypeScript for strong types.
- Rollup for bundling.
- Plain DOM APIs, no framework dependencies.
- CSS modular file for default styling.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumer Layer
    subgraph "Consumer Layer"
        ConsumerApp["Consumer Application"]:::consumer
        DataModel["Data Model"]:::consumer
        DOM["Browser DOM"]:::consumer
    end

    %% Library Source
    subgraph "Library Source"
        UI["LiquidBrainUI"]:::library
        Engine["LiquidBrainEngine"]:::library
        PublicAPI["Public API Exports"]:::library
        Types["Shared Type Definitions"]:::library
        CSSDefault["Default CSS Styles"]:::css
    end

    %% Build & Distribution
    subgraph "Build & Distribution"
        Bundler["Bundler / Build Pipeline"]:::build
        Dist["Distribution Artifacts"]:::build
        Npm["npm Registry / UMD Distribution"]:::build
        CSSDist["Distribution CSS Styles"]:::css
    end

    %% Config & Docs
    subgraph "Config & Docs"
        RollupCfg["rollup.config.cjs"]:::build
        TSConfig["tsconfig.json"]:::build
        PackageJson["package.json"]:::build
        Readme["readme.md"]:::build
        Gitignore[".gitignore"]:::build
    end

    %% Relationships
    ConsumerApp -->|"init(model, inputElement, markers, customRenderer)"| UI
    ConsumerApp -->|provides| DataModel
    UI -->|"handleFetchSuggestionsFromValue(value, cursor)"| Engine
    Engine -->|"suggestions list"| UI
    UI -->|"render modal"| DOM
    UI -->|"insertSuggestion"| Engine
    CSSDefault -.->|styles modal| UI
    CSSDist -.->|styles modal| Dist

    PublicAPI -->|exports UI & Engine & Types| UI
    PublicAPI -->|exports UI & Engine & Types| Engine
    PublicAPI -->|exports UI & Engine & Types| Types
    UI -->|imports types| Types
    Engine -->|imports types| Types

    UI & Engine & PublicAPI & Types & CSSDefault --> Bundler
    Bundler -->|compiles/transpiles| Dist
    Dist -->|published to| Npm

    RollupCfg --> Bundler
    TSConfig --> Bundler
    PackageJson --> Npm
    Readme -.-> Npm
    Gitignore -.-> Bundler

    %% Click Events
    click ConsumerApp "https://github.com/lordmendes/liquidbrain/blob/master/Examples/vanilla+html/index.html"
    click UI "https://github.com/lordmendes/liquidbrain/blob/master/src/LiquidBrainUI.ts"
    click Engine "https://github.com/lordmendes/liquidbrain/blob/master/src/LiquidBrainEngine.ts"
    click PublicAPI "https://github.com/lordmendes/liquidbrain/blob/master/src/index.ts"
    click Types "https://github.com/lordmendes/liquidbrain/blob/master/src/types.ts"
    click CSSDefault "https://github.com/lordmendes/liquidbrain/blob/master/src/liquidbrain.css"
    click CSSDist "https://github.com/lordmendes/liquidbrain/blob/master/liquidbrain.css"
    click RollupCfg "https://github.com/lordmendes/liquidbrain/blob/master/rollup.config.cjs"
    click TSConfig "https://github.com/lordmendes/liquidbrain/blob/master/tsconfig.json"
    click PackageJson "https://github.com/lordmendes/liquidbrain/blob/master/package.json"
    click Readme "https://github.com/lordmendes/liquidbrain/blob/master/readme.md"
    click Gitignore "https://github.com/lordmendes/liquidbrain/blob/master/.gitignore"

    %% Styles
    classDef library fill:#ADD8E6,stroke:#000
    classDef consumer fill:#90EE90,stroke:#000
    classDef build fill:#FFA500,stroke:#000
    classDef css fill:#D3D3D3,stroke:#000
```
