# c4rlos-mor4n/builderbot architecture

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

- Interactive diagram: https://gitdiagram.com/c4rlos-mor4n/builderbot
- Repository: https://github.com/c4rlos-mor4n/builderbot

## Overview

##### Project Type & Purpose
- Monorepo of TypeScript/JavaScript packages, managed via Lerna & Nx
- Core “bot” library to define conversation flows, plus auxiliary packages:
– CLI tool (“packages/cli”) to scaffold new projects
– Context packages (“contexts-*”) to plug in NLP/UI contexts (e.g., Dialogflow)
– Provider packages (“provider-*”) to connect to different WhatsApp vendors (Baileys, Twilio, Venom, etc.)
– Database adapters (“database-*”) for pluggable persistence (JSON, Mongo, MySQL, Postgres)
– ESLint plugin to enforce flow patterns
– “create-builderbot” project generator
– Starter templates under “starters/apps”

Purpose: enable developers to build provider-agnostic, stateful chatbots on WhatsApp with pluggable contexts & persistence.

##### File Structure
Top‐level files
- lerna.json / nx.json: monorepo orchestration
- package.json / pnpm-workspace.yaml: workspaces setup
packages/
- bot: core runtime (flow engine, event emitter, IO, context, utils)
- cli: scaffolder and developer CLI
- contexts-*: context plugins
- provider-*: vendor adapters implementing a common provider interface
- database-*: persistence adapters
- eslint-plugin-builderbot: lint rules for flow definitions
- create-builderbot: interactive project generator
scripts/: code generators for templates & CI/CD helpers
starters/: ready-made app templates combining bot, provider, db

##### README Insights
- “npm create builderbot” to bootstrap an app
- Library is provider-agnostic and highly extensible via plugins
- Official docs website describes flows, API, plugin authoring

##### Main Components & Their Interactions
a. Components
1. Developer (CLI)
2. Generated App – uses @builderbot/bot (core)
3. Bot Core
- Flow Engine
- Event Emitter
- Context Manager
- IO layer (transforms, serializers)
4. Provider Plugins
- Adapter implements send/receive interface
5. Context Plugins
- Provide NLP or canned‐response capabilities
6. Database Adapters
- Persist conversation state, global state
7. CI/CD / Build Tools
- Lerna, Nx, Rollup, Jest tests
b. Relationships & Data Flow
1. Incoming message from WhatsApp vendor → Provider Plugin
2. Provider unwraps message → Bot Core IO layer
3. Core Event Emitter → Flow Engine / Context Manager
4. Flow Engine applies user-defined flows → may read/write Conversation State via Database Adapter
5. Generated outgoing actions → IO methods → Provider Plugin → WhatsApp vendor
6. CLI & `create-builderbot` generate starter apps connecting these packages
c. Architectural Patterns & Principles
- Plugin/Adapter Pattern: providers, contexts, databases all conform to common interfaces
- Inversion of Control: Bot Core depends on abstractions (interfaces) implemented by plugins
- Monorepo for cohesive versioning & sharing code
- Separation of concerns: core engine vs IO vs persistence vs provider vs context
d. Key Technologies & Frameworks
- Node.js + TypeScript
- Lerna & Nx workspaces
- Rollup for bundling each package
- Jest for unit/e2e testing
- ESLint plugin for flow patterns
- pnpm workspaces

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Tools
    subgraph "Developer Tools" 
        direction TB
        CLI["Developer CLI"]:::developer
        Create["Project Generator<br/>(npm create builderbot)"]:::generator
    end

    %% Starter Apps
    subgraph "Starter App Templates" 
        direction TB
        Starters["starters/apps"]:::starter
    end

    %% Bot Core
    subgraph "Bot Core (@builderbot/bot)" 
        direction TB
        Core["Flow Engine"]:::core
        Emitter["Event Emitter"]:::core
        ContextMgr["Context Manager"]:::core
        IO["IO Layer"]:::core
    end

    %% Provider Plugins
    subgraph "Provider Plugins" 
        direction TB
        PBaal["provider-baileys"]:::provider
        PTwilio["provider-twilio"]:::provider
        PMeta["provider-meta"]:::provider
    end

    %% Context Plugins
    subgraph "Context Plugins" 
        direction TB
        CDialog["contexts-dialogflow"]:::context
        CDialogCX["contexts-dialogflow-cx"]:::context
    end

    %% Database Adapters
    subgraph "Database Adapters" 
        direction TB
        DBJson["database-json"]:::database
        DBMongo["database-mongo"]:::database
        DBMySQL["database-mysql"]:::database
        DBPostgres["database-postgres"]:::database
    end

    %% CI/CD & Build
    subgraph "CI/CD & Build Tools" 
        direction TB
        Lerna["lerna.json"]:::tool
        Nx["nx.json"]:::tool
        CI[".github/workflows/ci.yml"]:::tool
        Scripts["scripts/"]:::tool
    end

    %% Connections
    CLI -->|"scaffolds"| Starters
    Create -->|"bootstraps"| Starters
    Starters -->|"uses"| Core
    %% Incoming message flow
    PBaal -->|"Incoming Message"| IO
    PTwilio -->|"Incoming Message"| IO
    PMeta -->|"Incoming Message"| IO
    %% Core internal flow
    IO -->|"emit event"| Emitter
    Emitter -->|"triggers"| Core
    Core -->|"manage context"| ContextMgr
    Core -->|"read/write state"| DBJson
    Core -->|"read/write state"| DBMongo
    Core -->|"read/write state"| DBMySQL
    Core -->|"read/write state"| DBPostgres
    %% Context usage
    ContextMgr --> CDialog
    ContextMgr --> CDialogCX
    %% Outgoing
    Core -->|"Outgoing Actions"| IO
    IO -->|"send to vendor"| PBaal
    IO -->|"send to vendor"| PTwilio
    IO -->|"send to vendor"| PMeta
    %% CI/CD dependencies
    Lerna --> Nx
    Nx --> Scripts
    Scripts --> CI

    %% Click Events
    click CLI "https://github.com/c4rlos-mor4n/builderbot/tree/builderbot/packages/cli"
    click CLI "https://github.com/c4rlos-mor4n/builderbot/blob/builderbot/packages/cli/src/index.ts"
    click CLI "https://github.com/c4rlos-mor4n/builderbot/blob/builderbot/packages/cli/bin/cli.cjs"
    click Create "https://github.com/c4rlos-mor4n/builderbot/tree/builderbot/packages/create-builderbot"
    click Create "https://github.com/c4rlos-mor4n/builderbot/blob/builderbot/packages/create-builderbot/src/index.ts"
    click Create "https://github.com/c4rlos-mor4n/builderbot/blob/builderbot/packages/create-builderbot/bin/create.cjs"
    click Core "https://github.com/c4rlos-mor4n/builderbot/tree/builderbot/packages/bot"
    click Core "https://github.com/c4rlos-mor4n/builderbot/blob/builderbot/packages/bot/src/core/coreClass.ts"
    click Emitter "https://github.com/c4rlos-mor4n/builderbot/blob/builderbot/packages/bot/src/core/eventEmitterClass.ts"
    click ContextMgr "https://github.com/c4rlos-mor4n/builderbot/blob/builderbot/packages/bot/src/context/index.ts"
    click IO "https://github.com/c4rlos-mor4n/builderbot/tree/builderbot/packages/bot/src/io"
    click DBJson "https://github.com/c4rlos-mor4n/builderbot/tree/builderbot/packages/database-json"
    click DBMongo "https://github.com/c4rlos-mor4n/builderbot/tree/builderbot/packages/database-mongo"
    click DBMySQL "https://github.com/c4rlos-mor4n/builderbot/tree/builderbot/packages/database-mysql"
    click DBPostgres "https://github.com/c4rlos-mor4n/builderbot/tree/builderbot/packages/database-postgres"
    click PBaal "https://github.com/c4rlos-mor4n/builderbot/tree/builderbot/packages/provider-baileys"
    click PTwilio "https://github.com/c4rlos-mor4n/builderbot/tree/builderbot/packages/provider-twilio"
    click PMeta "https://github.com/c4rlos-mor4n/builderbot/tree/builderbot/packages/provider-meta"
    click CDialog "https://github.com/c4rlos-mor4n/builderbot/tree/builderbot/packages/contexts-dialogflow"
    click CDialogCX "https://github.com/c4rlos-mor4n/builderbot/tree/builderbot/packages/contexts-dialogflow-cx"
    click Lerna "https://github.com/c4rlos-mor4n/builderbot/blob/builderbot/lerna.json"
    click Nx "https://github.com/c4rlos-mor4n/builderbot/blob/builderbot/nx.json"
    click CI "https://github.com/c4rlos-mor4n/builderbot/blob/builderbot/.github/workflows/ci.yml"
    click Scripts "https://github.com/c4rlos-mor4n/builderbot/tree/builderbot/scripts/"

    %% Styles
    classDef core fill:#f9f,stroke:#333,stroke-width:1px
    classDef provider fill:#bbf,stroke:#333,stroke-width:1px
    classDef context fill:#bfb,stroke:#333,stroke-width:1px
    classDef database fill:#fbf,stroke:#333,stroke-width:1px
    classDef developer fill:#ffb,stroke:#333,stroke-width:1px
    classDef generator fill:#ff0,stroke:#333,stroke-width:1px
    classDef starter fill:#0ff,stroke:#333,stroke-width:1px
    classDef tool fill:#ccc,stroke:#333,stroke-width:1px
```
