# enrique-nunez/bot-whatsapp architecture

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

- Interactive diagram: https://gitdiagram.com/enrique-nunez/bot-whatsapp
- Repository: https://github.com/enrique-nunez/bot-whatsapp

## Overview

##### Project type and purpose
- This is an open‑source, full‑stack TypeScript monorepo for “BuilderBot,” a conversational‑flow framework and CLI tool.
- It uses Nx/Lerna for workspace management, Rollup for bundling, Jest for tests, Husky/Commitlint/Prettier/ESLint for quality, and GitHub Actions for CI/CD.
- Primary use case: let developers generate and run WhatsApp bots agnostic to provider, with pluggable database adapters and NLP/context integrations.

##### File structure
- Top‑level config: pnpm-workspace.yaml, nx.json, lerna.json, package.json
- packages/ contains:
- bot – core library that handles flows, state, events, I/O abstractions, utils
- cli – a CLI to create projects, run checks, install dependencies
- contexts‑* – Dialogflow/other context integrations
- database‑* – adapters for JSON, Mongo, MySQL, Postgres
- provider‑* – WhatsApp provider plugins (Baileys, Meta, Twilio, Venom, WPPConnect)
- eslint-plugin-builderbot – code linting rules for flow correctness
- starters/ holds templated app skeletons for each combination of provider + database + language (JS/TS)
- scripts/ orchestrates code generation, zone definitions, cleanup

##### README
- Describes “BuilderBot” as an agnostic WhatsApp bot framework plus a generator (npm create builderbot@latest).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer scaffolding flow
    Developer["Developer"]:::external
    Developer -->|"runs CLI"| CLI_Tool
    CLI_Tool -->|"generates"| Starter_App
    Starter_App -->|"imports Core & Plugins"| Developer_App

    %% Monorepo container
    subgraph "BuilderBot Monorepo"
        direction TB

        %% Monorepo infra
        subgraph "Monorepo Management"
            direction TB
            Lerna["lerna.json"]:::monorepoInfra
            NxConfig["nx.json"]:::monorepoInfra
            PnpmWS["pnpm-workspace.yaml"]:::monorepoInfra
        end

        %% Build & CI Pipeline
        subgraph "Build & CI Pipeline"
            direction TB
            CI_Workflows["CI Workflows"]:::monorepoInfra
            Releases["Release Workflows"]:::monorepoInfra
            Rollup_Bot["rollup.config.js (bot)"]:::monorepoInfra
            Rollup_CLI["rollup.config.js (cli)"]:::monorepoInfra
            Other_Rollup["rollup.config.js (others)"]:::monorepoInfra
        end

        %% Core Bot Library
        subgraph "Core Bot Library" 
            direction TB
            Bot_Pkg["packages/bot/"]:::core
            Core_Class["coreClass.ts"]:::core
            IO_Module["io/"]:::core
            DB_Module["db/index.ts"]:::core
        end

        %% CLI & Generator
        subgraph "CLI & Generator"
            direction TB
            CLI_Tool["Builderbot CLI"]:::cli
            CLI_Src["src/index.ts"]:::cli
            Generator["Create-Builderbot"]:::cli
            Gen_Src["src/index.ts"]:::cli
        end

        %% Plugins
        subgraph "Provider Plugins"
            direction TB
            PBail["provider-baileys/"]:::plugin
            PMeta["provider-meta/"]:::plugin
            PTwilio["provider-twilio/"]:::plugin
            PVenom["provider-venom/"]:::plugin
            PWeb["provider-web-whatsapp/"]:::plugin
            PWPP["provider-wppconnect/"]:::plugin
        end

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

        subgraph "Context Integrations"
            direction TB
            CDialogflow["contexts-dialogflow/"]:::plugin
            CDialogflowCX["contexts-dialogflow-cx/"]:::plugin
        end

        %% ESLint Plugin
        subgraph "ESLint Plugin"
            direction TB
            ESLintPkg["eslint-plugin-builderbot/"]:::plugin
            ESLintRules["src/rules/"]:::plugin
        end

        %% Starters/Templates
        subgraph "Starters/Templates"
            direction TB
            StartersApps["starters/apps/"]:::cli
            StarterCombos["base-*-*-*/"]:::cli
        end

        %% Supporting Scripts
        subgraph "Supporting Scripts"
            direction TB
            CleanScript["scripts/clean.ts"]:::scripts
            GenScript["scripts/generate/index.ts"]:::scripts
            TemplateScripts["scripts/generate/template/"]:::scripts
        end
    end

    %% Developer Application
    Developer_App["Starter App"]:::core

    %% Runtime External Systems
    subgraph "External Services"
        direction TB
        WhatsAppAPI["WhatsApp API"]:::external
        ExternalDB["External Database"]:::external
        NLPService["NLP Service"]:::external
    end

    %% Runtime flow
    WhatsAppAPI -->|incoming message| PBail
    PBail -->|normalized event| Bot_Pkg
    Bot_Pkg -->|reads/writes state| DBJson
    DBJson -->|persist| ExternalDB
    Bot_Pkg -->|calls context| CDialogflow
    CDialogflow -->|API call| NLPService
    Bot_Pkg -->|reply| PBail
    PBail -->|send message| WhatsAppAPI

    %% Relationships
    Bot_Pkg -->|implements IProvider| PBail
    Bot_Pkg -->|implements IDataAdapter| DBJson
    Bot_Pkg -->|implements IContext| CDialogflow
    CLI_Tool -->|uses Core| Bot_Pkg
    CLI_Tool -->|uses Plugins| PBail
    CLI_Tool -->|uses Adapters| DBJson
    CLI_Tool -->|uses Contexts| CDialogflow
    CLI_Tool -->|uses ESLint Rules| ESLintPkg
    CLI_Tool -->|uses Scripts| GenScript
    CI_Workflows -->|runs tests| Bot_Pkg
    CI_Workflows -->|runs lint| ESLintPkg
    Rollup_Bot -->|bundles| Bot_Pkg
    Rollup_CLI -->|bundles| CLI_Tool

    %% Click Events
    click Lerna "https://github.com/enrique-nunez/bot-whatsapp/blob/builderbot/lerna.json"
    click NxConfig "https://github.com/enrique-nunez/bot-whatsapp/blob/builderbot/nx.json"
    click PnpmWS "https://github.com/enrique-nunez/bot-whatsapp/blob/builderbot/pnpm-workspace.yaml"
    click CI_Workflows "https://github.com/enrique-nunez/bot-whatsapp/blob/builderbot/.github/workflows/ci.yml"
    click Releases "https://github.com/enrique-nunez/bot-whatsapp/blob/builderbot/.github/workflows/releases.yml"
    click Rollup_Bot "https://github.com/enrique-nunez/bot-whatsapp/blob/builderbot/packages/bot/rollup.config.js"
    click Rollup_CLI "https://github.com/enrique-nunez/bot-whatsapp/blob/builderbot/packages/cli/rollup.config.js"
    click CLI_Tool "https://github.com/enrique-nunez/bot-whatsapp/tree/builderbot/packages/cli/"
    click CLI_Src "https://github.com/enrique-nunez/bot-whatsapp/blob/builderbot/packages/cli/src/index.ts"
    click Generator "https://github.com/enrique-nunez/bot-whatsapp/tree/builderbot/packages/create-builderbot/"
    click Gen_Src "https://github.com/enrique-nunez/bot-whatsapp/blob/builderbot/packages/create-builderbot/src/index.ts"
    click Bot_Pkg "https://github.com/enrique-nunez/bot-whatsapp/tree/builderbot/packages/bot/"
    click Core_Class "https://github.com/enrique-nunez/bot-whatsapp/blob/builderbot/packages/bot/src/core/coreClass.ts"
    click IO_Module "https://github.com/enrique-nunez/bot-whatsapp/tree/builderbot/packages/bot/src/io/"
    click DB_Module "https://github.com/enrique-nunez/bot-whatsapp/blob/builderbot/packages/bot/src/db/index.ts"
    click PBail "https://github.com/enrique-nunez/bot-whatsapp/tree/builderbot/packages/provider-baileys/"
    click PMeta "https://github.com/enrique-nunez/bot-whatsapp/tree/builderbot/packages/provider-meta/"
    click PTwilio "https://github.com/enrique-nunez/bot-whatsapp/tree/builderbot/packages/provider-twilio/"
    click PVenom "https://github.com/enrique-nunez/bot-whatsapp/tree/builderbot/packages/provider-venom/"
    click PWeb "https://github.com/enrique-nunez/bot-whatsapp/tree/builderbot/packages/provider-web-whatsapp/"
    click PWPP "https://github.com/enrique-nunez/bot-whatsapp/tree/builderbot/packages/provider-wppconnect/"
    click DBJson "https://github.com/enrique-nunez/bot-whatsapp/tree/builderbot/packages/database-json/"
    click DBMongo "https://github.com/enrique-nunez/bot-whatsapp/tree/builderbot/packages/database-mongo/"
    click DBMySQL "https://github.com/enrique-nunez/bot-whatsapp/tree/builderbot/packages/database-mysql/"
    click DBPostgres "https://github.com/enrique-nunez/bot-whatsapp/tree/builderbot/packages/database-postgres/"
    click CDialogflow "https://github.com/enrique-nunez/bot-whatsapp/tree/builderbot/packages/contexts-dialogflow/"
    click CDialogflowCX "https://github.com/enrique-nunez/bot-whatsapp/tree/builderbot/packages/contexts-dialogflow-cx/"
    click ESLintPkg "https://github.com/enrique-nunez/bot-whatsapp/tree/builderbot/packages/eslint-plugin-builderbot/"
    click ESLintRules "https://github.com/enrique-nunez/bot-whatsapp/tree/builderbot/packages/eslint-plugin-builderbot/src/rules/"
    click StartersApps "https://github.com/enrique-nunez/bot-whatsapp/tree/builderbot/starters/apps/"
    click StarterCombos "https://github.com/enrique-nunez/bot-whatsapp/tree/builderbot/starters/apps/base-*-*-*/"
    click CleanScript "https://github.com/enrique-nunez/bot-whatsapp/blob/builderbot/scripts/clean.ts"
    click GenScript "https://github.com/enrique-nunez/bot-whatsapp/blob/builderbot/scripts/generate/index.ts"
    click TemplateScripts "https://github.com/enrique-nunez/bot-whatsapp/tree/builderbot/scripts/generate/template/"

    %% Styles
    classDef monorepoInfra fill:#DDDDDD,stroke:#333,stroke-width:1px
    classDef core fill:#CCDDEE,stroke:#333,stroke-width:1px
    classDef plugin fill:#CCEECC,stroke:#333,stroke-width:1px
    classDef cli fill:#FFCC99,stroke:#333,stroke-width:1px
    classDef external fill:#DDBBFF,stroke:#333,stroke-width:1px
    classDef scripts fill:#FFE4B5,stroke:#333,stroke-width:1px
```
