# hubtype/botonic architecture

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

- Interactive diagram: https://gitdiagram.com/hubtype/botonic
- Repository: https://github.com/hubtype/botonic

## Overview

##### Main Components
- CLI Interface: Represented by the “botonic-cli” package (located in packages/botonic-cli) that provides commands (new, serve, deploy, etc.) and orchestrates project creation and local development.
- Core Engine: Depicted by “botonic-core” which contains the routing, event models, bot logic, handoff, and internal models. This is the heart of processing message events and driving the conversation flow.
- Frontend (UI Layer): The “botonic-react” package embodies the client-side chatbot UI. It includes components for webchat, multichannel integration, and testing elements.
- Plugins and Extensions: Various plugin packages integrate functionalities such as analytics (Google Analytics, Segment, Dashbot), CMS connections (Contentful, etc.), and NLU capabilities (Dialogflow, Watson, Luis, Inbenta). These plugins extend the core engine to connect to external services.
- Bundlers and DX Tools: Packages like “botonic-dx-bundler-rspack”, “botonic-dx-bundler-webpack”, and “botonic-dx” show how the code is built, bundled, and prepared for production deployments.
- Examples & Documentation: The “examples” folder contains several bot project examples showcasing different approaches (e.g., blank, booking-platform, childs, custom-webchat, etc.). The “docs” folder holds comprehensive documentation, component guides, and technical details.

##### Relationships and Interactions
- The CLI tool (botonic-cli) acts as the entry point for developers, allowing them to scaffold new projects (via “botonic new”), serve the application locally, and deploy it.
- The CLI invokes the Core Engine (botonic-core) which manages conversational flows, routes incoming messages, and triggers bot actions.
- The Core Engine communicates with various Plugins to handle functions such as analytics tracking, content management, and natural language understanding.
- Data flows toward the Frontend (botonic-react) where the React components manage webchat UI, display messages, handle interactive components (e.g., carousels, buttons, multimedia), and synchronize with backend events.
- External services (messaging platforms like WhatsApp, Facebook Messenger, etc.) integrate with the bot infrastructure, usually via webhooks or serverless functions, as supported by the core and plugins.
- Build scripts, tests, CI workflows (under .github/workflows, scripts/ci, etc.) ensure continuous integration and deployment of the framework, verifying unit tests and integration tests across components.

##### Architectural Patterns and Design Principles
- Modular Architecture: Each part of the system (CLI, core, front-end, plugins) is separated into distinct packages, promoting reusability and easy maintenance.
- Plugin-Based Extensibility: The design encourages adding integrations as independent modules which interact with the core bot engine.
- Full-Stack Separation: Emphasis on decoupling the conversational logic (backend/serverless core) from the user interface (React based frontend), making it easier to swap or update either layer without affecting the other.
- Use of Standard Tools: Technologies like React, serverless architecture, and CI/CD pipelines (with GitHub Actions) are used for development, testing, and deploying the framework.

## Diagram (Mermaid)

```mermaid
flowchart TD
    CLI["botonic-cli\n(CLI Interface)"]:::cli
    CORE["botonic-core\n(Core Bot Engine)"]:::core
    FRONTEND["botonic-react\n(React Chat UI)"]:::frontend
    EXT["External Messaging Platforms/Services"]:::external

    %% Main flow connections
    CLI -->|"invokes"| CORE
    CORE -->|"flows_to"| FRONTEND

    %% Plugins & Integrations subgraph with aggregator header
    subgraph "Plugins & Integrations"
        PLG_HEADER["Plugins & Integrations"]:::pluginHeader
        P1["Contentful Plugin"]:::plugin
        P2["Dashbot Plugin"]:::plugin
        P3["Dialogflow Plugin"]:::plugin
        P4["DynamoDB Plugin"]:::plugin
        P5["Flow Builder Plugin"]:::plugin
        P6["Google Analytics Plugin"]:::plugin
        P7["Google Translation Plugin"]:::plugin
        P8["Hubtype Analytics Plugin"]:::plugin
        P9["Hubtype Babel Plugin"]:::plugin
        P10["Inbenta Plugin"]:::plugin
        P11["Knowledge Bases Plugin"]:::plugin
        P12["Luis Plugin"]:::plugin
        P13["Segment Plugin"]:::plugin
        P14["Watson Plugin"]:::plugin

        PLG_HEADER --> P1
        PLG_HEADER --> P2
        PLG_HEADER --> P3
        PLG_HEADER --> P4
        PLG_HEADER --> P5
        PLG_HEADER --> P6
        PLG_HEADER --> P7
        PLG_HEADER --> P8
        PLG_HEADER --> P9
        PLG_HEADER --> P10
        PLG_HEADER --> P11
        PLG_HEADER --> P12
        PLG_HEADER --> P13
        PLG_HEADER --> P14
    end

    %% Connection from Core to Plugins aggregator and then to External Messaging Platforms
    CORE -->|"triggers"| PLG_HEADER
    PLG_HEADER -->|"communicates"| EXT

    %% Bundlers & DX Tools subgraph with aggregator header
    subgraph "Bundlers & DX Tools"
        BDH["Bundlers & DX Tools"]:::bundlerHeader
        B1["rspack Bundler"]:::bundler
        B2["webpack Bundler"]:::bundler
        B3["DX Tools"]:::bundler
        BDH --> B1
        BDH --> B2
        BDH --> B3
    end

    %% Examples & Documentation subgraph with aggregator header
    subgraph "Examples & Documentation"
        EXHDR["Examples & Documentation"]:::supportHeader
        E1["Examples"]:::support
        E2["Documentation"]:::support
        EXHDR --> E1
        EXHDR --> E2
    end

    %% Connections from CLI to supporting tools
    CLI -->|"build_deploy"| BDH
    CLI -->|"docs_support"| EXHDR

    %% Styles
    classDef cli fill:#f9e79f,stroke:#d4ac0d,stroke-width:2px;
    classDef core fill:#aed6f1,stroke:#2980b9,stroke-width:2px;
    classDef frontend fill:#a9dfbf,stroke:#27ae60,stroke-width:2px;
    classDef plugin fill:#f5cba7,stroke:#d35400,stroke-width:2px;
    classDef pluginHeader fill:#f0b27a,stroke:#d35400,stroke-width:2px;
    classDef bundler fill:#d7bde2,stroke:#8e44ad,stroke-width:2px;
    classDef bundlerHeader fill:#c39bd3,stroke:#8e44ad,stroke-width:2px;
    classDef support fill:#bb8fce,stroke:#6c3483,stroke-width:2px;
    classDef supportHeader fill:#af7ac5,stroke:#6c3483,stroke-width:2px;
    classDef external fill:#ff9999,stroke:#ff4d4d,stroke-width:2px;

    %% Click Events
    click CLI "https://github.com/hubtype/botonic/tree/master-lts/packages/botonic-cli"
    click CORE "https://github.com/hubtype/botonic/tree/master-lts/packages/botonic-core"
    click FRONTEND "https://github.com/hubtype/botonic/tree/master-lts/packages/botonic-react"
    click P1 "https://github.com/hubtype/botonic/tree/master-lts/packages/botonic-plugin-contentful"
    click P2 "https://github.com/hubtype/botonic/tree/master-lts/packages/botonic-plugin-dashbot"
    click P3 "https://github.com/hubtype/botonic/tree/master-lts/packages/botonic-plugin-dialogflow"
    click P4 "https://github.com/hubtype/botonic/tree/master-lts/packages/botonic-plugin-dynamodb"
    click P5 "https://github.com/hubtype/botonic/tree/master-lts/packages/botonic-plugin-flow-builder"
    click P6 "https://github.com/hubtype/botonic/tree/master-lts/packages/botonic-plugin-google-analytics"
    click P7 "https://github.com/hubtype/botonic/tree/master-lts/packages/botonic-plugin-google-translation"
    click P8 "https://github.com/hubtype/botonic/tree/master-lts/packages/botonic-plugin-hubtype-analytics"
    click P9 "https://github.com/hubtype/botonic/tree/master-lts/packages/botonic-plugin-hubtype-babel"
    click P10 "https://github.com/hubtype/botonic/tree/master-lts/packages/botonic-plugin-inbenta"
    click P11 "https://github.com/hubtype/botonic/tree/master-lts/packages/botonic-plugin-knowledge-bases"
    click P12 "https://github.com/hubtype/botonic/tree/master-lts/packages/botonic-plugin-luis"
    click P13 "https://github.com/hubtype/botonic/tree/master-lts/packages/botonic-plugin-segment"
    click P14 "https://github.com/hubtype/botonic/tree/master-lts/packages/botonic-plugin-watson"
    click B1 "https://github.com/hubtype/botonic/tree/master-lts/packages/botonic-dx-bundler-rspack"
    click B2 "https://github.com/hubtype/botonic/tree/master-lts/packages/botonic-dx-bundler-webpack"
    click B3 "https://github.com/hubtype/botonic/tree/master-lts/packages/botonic-dx"
    click E1 "https://github.com/hubtype/botonic/tree/master-lts/examples"
    click E2 "https://github.com/hubtype/botonic/tree/master-lts/docs"
```
