How c4rlos-mor4n/builderbot works
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