# andersonba/yve-bot architecture

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

- Interactive diagram: https://gitdiagram.com/andersonba/yve-bot
- Repository: https://github.com/andersonba/yve-bot

## Overview

##### Project type and purpose
- yve-bot is an open-source JavaScript/TypeScript SDK for building rule-based chatbot conversations that run both in Node and in the browser.
- The README and docs show it provides a “core engine” (state machine, actions, listeners, validators), an extensibility layer for custom types/validators, and a UI bundle to render chats in the browser.
- It ships via npm, builds with Rollup, and includes examples (CLI, web, React, Socket.io) plus a documentation website.

##### File structure
- Top-level source folders under src/
- src/core: the engine implementing state, actions, controllers, store, validators, sanitizers, exceptions
- src/ext: extension points for custom types (e.g. StringSearch)
- src/ui: the UI adapter that listens to core events and renders messages
- src/types.d.ts: shared interfaces
- Build output under lib/: core.js, ui.js, web.js, ext/types
- Configuration: rollup.config.ts, tsconfig.json, tslint.json
- Examples under examples/: CLI, Facebook bot, React, plain web, Socket.io
- Documentation site in website/: built with Docusaurus, serves docs and playground.

##### README for additional insights
- The engine is loaded with a YAML or JS ruleset, then routed through core API: controller.handle(), store updates, listeners emit “send message” events.
- The UI layer subscribes to core’s event emitter and updates DOM or console.
- Extensions plug into core.types or core.validators to add custom behavior.
- The build produces separate bundles for “core”, “ui”, and “web” targets.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration
    Config["Config<br/>(YAML/JS)"]:::config

    %% Core Engine Subgraph
    subgraph "Rule-based Bot Core Engine"
        direction TB
        CoreIndex["src/core/index.ts"]:::core
        Controller["controller.ts"]:::core
        Actions["actions.ts"]:::core
        Store["store.ts"]:::core
        Listeners["listeners.ts"]:::core
        Validators["validators.ts"]:::core
        Sanitizers["sanitizers.ts"]:::core
        TypesUtils["types.ts<br/>utils.ts"]:::core
        Exceptions["exceptions.ts"]:::core
    end

    %% Extension/Plugin Layer
    subgraph "Extension/Plugin Layer"
        direction TB
        ExtDir["src/ext/types/"]:::ext
        StringSearch["StringSearch.js"]:::ext
        ExtTests["StringSearch.spec.ts"]:::ext
    end

    %% UI Adapter Subgraph
    subgraph "UI Adapter"
        direction TB
        UIIndex["src/ui/index.ts"]:::ui
        UITool["ui.ts<br/>utils.ts"]:::ui
        UITests["bot.spec.ts<br/>utils.spec.ts"]:::ui
    end

    %% Rendering Targets
    subgraph "Rendering Targets"
        direction TB
        DOM["Browser DOM"]:::target
        Console["CLI Console"]:::target
        SocketClient["Socket.io Client"]:::target
    end

    %% Build & Packaging Pipeline
    subgraph "Build & Packaging Pipeline"
        direction TB
        RollupConfig["rollup.config.ts"]:::build
        TSConfig["tsconfig.json"]:::build
        TSLint["tslint.json"]:::build
        Outputs["Bundles: core.js<br/>ui.js<br/>web.js"]:::build
    end

    %% Examples & Integrations
    subgraph "Examples & Integrations"
        direction TB
        CLIExample["examples/cli/index.js"]:::example
        FBExample["examples/facebook/index.js"]:::example
        ReactExample["examples/react/src/App.js"]:::example
        WebExample["examples/web/client.js"]:::example
        SocketServer["examples/socket.io/index.js"]:::example
        SocketClientEx["examples/socket.io/client.js"]:::example
    end

    %% Documentation & CI
    subgraph "Documentation & CI"
        direction TB
        DocsContent["docs/"]:::doc
        Website["website/"]:::doc
        CI[".github/workflows/ci.yml"]:::doc
    end

    %% NPM Registry
    NPM["npm Registry"]:::build

    %% Connections
    Config -->|Load ruleset| CoreIndex
    CoreIndex --> Controller
    CoreIndex --> Actions
    CoreIndex --> Store
    CoreIndex --> Listeners
    CoreIndex --> Validators
    CoreIndex --> Sanitizers
    CoreIndex --> TypesUtils
    CoreIndex --> Exceptions

    CoreIndex <--> ExtDir
    ExtDir --> StringSearch
    StringSearch --> ExtTests

    CoreIndex --> UIIndex
    UIIndex --> UITool
    UIIndex --> UITests
    UIIndex --> DOM
    UIIndex --> Console
    UIIndex --> SocketClient

    %% Build flow
    CoreIndex --> RollupConfig
    UIIndex --> RollupConfig
    ExtDir --> RollupConfig
    RollupConfig --> Outputs
    Outputs --> NPM
    NPM --> CLIExample
    NPM --> FBExample
    NPM --> ReactExample
    NPM --> WebExample
    NPM --> SocketServer
    NPM --> SocketClientEx

    DocsContent --> Website

    %% Click Events
    click CoreIndex "https://github.com/andersonba/yve-bot/blob/master/src/core/index.ts"
    click Controller "https://github.com/andersonba/yve-bot/blob/master/src/core/controller.ts"
    click Actions "https://github.com/andersonba/yve-bot/blob/master/src/core/actions.ts"
    click Store "https://github.com/andersonba/yve-bot/blob/master/src/core/store.ts"
    click Listeners "https://github.com/andersonba/yve-bot/blob/master/src/core/listeners.ts"
    click Validators "https://github.com/andersonba/yve-bot/blob/master/src/core/validators.ts"
    click Sanitizers "https://github.com/andersonba/yve-bot/blob/master/src/core/sanitizers.ts"
    click TypesUtils "https://github.com/andersonba/yve-bot/blob/master/src/core/types.ts"
    click TypesUtils "https://github.com/andersonba/yve-bot/blob/master/src/core/utils.ts"
    click Exceptions "https://github.com/andersonba/yve-bot/blob/master/src/core/exceptions.ts"

    click ExtDir "https://github.com/andersonba/yve-bot/tree/master/src/ext/types/"
    click StringSearch "https://github.com/andersonba/yve-bot/blob/master/lib/ext/types/StringSearch.js"
    click ExtTests "https://github.com/andersonba/yve-bot/blob/master/src/ext/types/__tests__/StringSearch.spec.ts"

    click UIIndex "https://github.com/andersonba/yve-bot/blob/master/src/ui/index.ts"
    click UITool "https://github.com/andersonba/yve-bot/blob/master/src/ui/ui.ts"
    click UITool "https://github.com/andersonba/yve-bot/blob/master/src/ui/utils.ts"
    click UITests "https://github.com/andersonba/yve-bot/blob/master/src/ui/__tests__/bot.spec.ts"
    click UITests "https://github.com/andersonba/yve-bot/blob/master/src/ui/__tests__/utils.spec.ts"
    click Outputs "https://github.com/andersonba/yve-bot/blob/master/lib/web.js"

    click RollupConfig "https://github.com/andersonba/yve-bot/blob/master/rollup.config.ts"
    click TSConfig "https://github.com/andersonba/yve-bot/blob/master/tsconfig.json"
    click TSLint "https://github.com/andersonba/yve-bot/blob/master/tslint.json"

    click CLIExample "https://github.com/andersonba/yve-bot/blob/master/examples/cli/index.js"
    click FBExample "https://github.com/andersonba/yve-bot/blob/master/examples/facebook/index.js"
    click ReactExample "https://github.com/andersonba/yve-bot/blob/master/examples/react/src/App.js"
    click WebExample "https://github.com/andersonba/yve-bot/blob/master/examples/web/client.js"
    click SocketServer "https://github.com/andersonba/yve-bot/blob/master/examples/socket.io/index.js"
    click SocketClientEx "https://github.com/andersonba/yve-bot/blob/master/examples/socket.io/client.js"

    click DocsContent "https://github.com/andersonba/yve-bot/tree/master/docs/"
    click Website "https://github.com/andersonba/yve-bot/tree/master/website/"
    click CI "https://github.com/andersonba/yve-bot/blob/master/.github/workflows/ci.yml"

    %% Styles
    classDef config fill:#f9f,stroke:#333,stroke-width:1px
    classDef core fill:#bbdefb,stroke:#1e88e5,stroke-width:1px
    classDef ext fill:#c8e6c9,stroke:#43a047,stroke-width:1px
    classDef ui fill:#ffe0b2,stroke:#fb8c00,stroke-width:1px
    classDef build fill:#eeeeee,stroke:#757575,stroke-width:1px
    classDef example fill:#e1bee7,stroke:#8e24aa,stroke-width:1px
    classDef doc fill:#d7ccc8,stroke:#6d4c41,stroke-width:1px
    classDef target fill:#fff9c4,stroke:#fbc02d,stroke-width:1px
```
