# botpress/v12 architecture

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

- Interactive diagram: https://gitdiagram.com/botpress/v12
- Repository: https://github.com/botpress/v12

## Overview

##### Project type and purpose
- Botpress is a full-stack, extensible chatbot development platform.
- It consists of a Node.js/TypeScript server that hosts a plugin-based “core” plus dozens of feature modules, and a React-based admin/studio UI (and a lightweight UI for embedding).
- The platform offers built-in natural language processing (NLU), messaging channel integrations, a flow designer, and a module/plugin ecosystem.

##### File structure
- Top-level “packages/bp” contains the core server code (Express-style HTTP API, real-time socket, module loader, DI container).
- “modules/*” holds individual features (analytics, basic-skills, builtin, nlu, hitl, channel-web, code-editor, etc.) each with its own backend API, hooks, content-types, views (full & lite), migrations, translations.
- “packages/ui-admin” and “packages/ui-lite” are the React-Redux admin and lightweight embeddable web clients.
- “examples” and “bench” folders illustrate sample bots, custom components, stress tests.
- Config files include Dockerfile, Kubernetes/heroku.yml, CI pipeline workflows under .github/workflows.
- Build tools: Gulp, Webpack (module-builder), Babel, TS config, migration scripts (Knex).

##### README for additional insights
- Deploy via binary, Docker image, or source.
- Plugin architecture: modules loaded dynamically at runtime.

##### Main components
a. Core Server (Node.js/TypeScript)
- HTTP API Layer (Express + custom routers)
- Real-time Layer (Socket.io JWT gateway)
- Module Loader (Inversify DI, plugin registry)
- Event Engine & Job Queue (in-memory + Redis for distributed jobs)
- BPM/Flow Engine (Dialog engine, instruction queue)
- NLU Service (embedded or external)
- Action Server (local or external process for user code)
- Storage:
- Relational DB (PostgreSQL/SQLite via Knex + migrations)
- File System driver (ghost FS for bot assets)
- Distributed sub-services: Redis for locks/queues, optional message broker.

b. Modules
- Each module registers backend API endpoints, database migrations, hooks, content types, views.
- Key modules: basic-skills, analytics, broadcasting, channel-web (webchat), nlu, hitl/hitlnext (human-in-the-loop), code-editor, uipath, etc.

c. Front-end Clients
- UI-Admin (React+Redux SPA for bot & workspace administration, health, channels, modules)
- UI-Lite (embeddable React component for chat UI)
- Channel-Web (fully featured web chat client)

d. External Integrations
- Messaging Channels (Slack, Messenger, Twilio, SMS, custom brokers)
- External NLU Engines (Rasa, Dialogflow, LUIS)
- Webhooks & custom modules via SDK

##### Relationships and interactions
- Clients ↔ HTTP API (REST/JSON) for configuration, content, user management, analytics.
- Chat clients ↔ Real-time Socket (bi-directional chat events).
- Core Server ↔ Database for persistence (config, dialogs, events, metrics).
- Core Server ↔ File system for bot assets, media (ghost FS).
- Core Server ↔ Redis for distributed locks, job queues.
- Core Server ↔ NLU component (local module “nlu” or external service).
- Core Server ↔ Action Server for executing user-provided code.
- Core Server ↔ Module plug-ins (dynamically loaded at startup).
- CI/CD & Build Pipeline ↔ Docker Hub / Artifactory.

##### Architectural patterns & design principles
- Plugin-based modular architecture (Inversify DI, dynamic module loader).
- Layered design: API layer, service layer, persistence layer, real-time layer.
- CQRS/Event-driven for dialog/instruction queue.
- Separation of concerns: core vs modules vs front-end.
- Micro-frontend pattern: each module can supply its own views in the admin UI.
- Containerization & Infrastructure as code (Docker, Kubernetes manifests).

##### Detailed capture of essential elements
- Core boot sequence: Inversify container loads modules → runs migrations → starts HTTP & real-time servers.
- Module lifecycle: module declares hooks, actions, views → core invokes hooks upon events.
- NLU pipeline: user message → core preprocessing → NLU module → intent/entities → dialog engine.
- Action execution: dialog engine enqueues instructions → instruction processor → action server (JS sandbox).
- Event storage: every incoming/outgoing event persisted in events table.
- UI updates: front-end subscribes to real-time events for chat and admin notifications.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Zone
    subgraph "Client Zone"
        direction TB
        UIAdmin["UI-Admin (React+Redux)"]:::client
        UILite["UI-Lite (Embed Chat)"]:::client
        ChannelWeb["Channel-Web Client"]:::client
    end

    %% API Zone / Core Services
    subgraph "API Zone / Core Server"
        direction TB
        CoreServer["Core Server\n(Node.js/TypeScript)"]:::service
        subgraph "HTTP & Real-time"
            direction TB
            API["HTTP API Layer\n(Express)"]:::service
            Realtime["Real-time Layer\n(Socket.io JWT)"]:::service
        end
        ModuleLoader["Module Loader\n(Inversify DI)"]:::service
        EventEngine["Event Engine & Job Queue"]:::queue
        FlowEngine["BPM/Flow Engine"]:::service
        NLUService["NLU Service"]:::service
        ActionServer["Action Server\n(User Code)"]:::service
    end

    %% Modules Zone
    subgraph "Modules"
        direction TB
        BasicSkills["basic-skills"]:::module
        AnalyticsMod["analytics"]:::module
        ChannelWebMod["channel-web"]:::module
        NLUMod["nlu"]:::module
        HITLMod["hitl"]:::module
        CodeEditor["code-editor"]:::module
    end

    %% Data Zone
    subgraph "Data Zone"
        direction TB
        Postgres["Relational DB\n(PostgreSQL/SQLite)"]:::db
        GhostFS["File System (Ghost FS)"]:::db
        Redis["Redis\n(Locks & Queues)"]:::queue
    end

    %% External Integrations
    subgraph "External Services"
        direction TB
        MsgChannels["Messaging Channels\n(Slack, SMS, Twilio)"]:::external
        ExtNLU["External NLU Engines\n(Rasa, Dialogflow)"]:::external
        CICD["CI/CD & Build Pipeline"]:::external
    end

    %% Client interactions
    UIAdmin -->|"REST API"| API
    UILite -->|"REST API"| API
    ChannelWeb -->|"WebSocket"| Realtime
    ChannelWeb -->|"REST API"| API

    %% Core internal flows
    API -->|"loads modules"| ModuleLoader
    API -->|"dispatch events"| EventEngine
    Realtime -->|"events"| EventEngine
    EventEngine -->|"triggers flows"| FlowEngine
    FlowEngine -->|"calls NLU"| NLUService
    FlowEngine -->|"enqueues actions"| EventEngine
    EventEngine -->|"executes"| ActionServer

    %% Module integration
    ModuleLoader --> BasicSkills
    ModuleLoader --> AnalyticsMod
    ModuleLoader --> ChannelWebMod
    ModuleLoader --> NLUMod
    ModuleLoader --> HITLMod
    ModuleLoader --> CodeEditor

    %% Persistence
    API -->|"queries"| Postgres
    API -->|"reads/writes"| GhostFS
    EventEngine -->|"queue storage"| Redis
    FlowEngine -->|"store instructions"| Redis
    ActionServer -->|"logs/results"| Postgres

    %% External services connections
    NLUService --> ExtNLU
    API --> MsgChannels

    CICD -->|"builds images"| CoreServer

    %% Click Events
    click CoreServer "https://github.com/botpress/v12/blob/master/packages/bp/src/core/app/server.ts"
    click API "https://github.com/botpress/v12/blob/master/packages/bp/src/core/app/api.ts"
    click API "https://github.com/botpress/v12/blob/master/packages/bp/src/core/routers/index.ts"
    click Realtime "https://github.com/botpress/v12/blob/master/packages/bp/src/core/realtime/realtime-service.ts"
    click Realtime "https://github.com/botpress/v12/blob/master/packages/bp/src/core/realtime/socket.io-jwt/index.ts"
    click ModuleLoader "https://github.com/botpress/v12/blob/master/packages/bp/src/core/modules/module-loader.ts"
    click ModuleLoader "https://github.com/botpress/v12/blob/master/packages/bp/src/core/modules/index.ts"
    click EventEngine "https://github.com/botpress/v12/blob/master/packages/bp/src/core/events/event-engine.ts"
    click EventEngine "https://github.com/botpress/v12/blob/master/packages/bp/src/core/events/queue/memory-queue.ts"
    click EventEngine "https://github.com/botpress/v12/blob/master/packages/bp/src/core/distributed/job-service.ts"
    click FlowEngine "https://github.com/botpress/v12/blob/master/packages/bp/src/core/dialog/dialog-engine.ts"
    click FlowEngine "https://github.com/botpress/v12/blob/master/packages/bp/src/core/dialog/instruction/queue.ts"
    click NLUService "https://github.com/botpress/v12/blob/master/packages/bp/src/core/services/nlu/nlu-service.ts"
    click NLUMod "https://github.com/botpress/v12/blob/master/modules/nlu/src/backend/api.ts"
    click ActionServer "https://github.com/botpress/v12/blob/master/packages/bp/src/core/user-code/action-server/local-action-server.ts"
    click ActionServer "https://github.com/botpress/v12/blob/master/packages/bp/src/orchestrator/action-server.ts"
    click Postgres "https://github.com/botpress/v12/blob/master/packages/bp/src/core/database/index.ts"
    click Postgres "https://github.com/botpress/v12/tree/master/packages/bp/src/migrations"
    click GhostFS "https://github.com/botpress/v12/blob/master/packages/bp/src/core/bpfs/ghost-service.ts"
    click GhostFS "https://github.com/botpress/v12/blob/master/packages/bp/src/core/bpfs/drivers/disk-driver.ts"
    click BasicSkills "https://github.com/botpress/v12/tree/master/modules/basic-skills"
    click AnalyticsMod "https://github.com/botpress/v12/tree/master/modules/analytics"
    click ChannelWebMod "https://github.com/botpress/v12/tree/master/modules/channel-web"
    click NLUMod "https://github.com/botpress/v12/tree/master/modules/nlu"
    click HITLMod "https://github.com/botpress/v12/tree/master/modules/hitl"
    click CodeEditor "https://github.com/botpress/v12/tree/master/modules/code-editor"
    click UIAdmin "https://github.com/botpress/v12/tree/master/packages/ui-admin/src"
    click UILite "https://github.com/botpress/v12/tree/master/packages/ui-lite/src"

    %% Styles
    classDef client fill:#D8BFD8,stroke:#9370DB
    classDef service fill:#ADD8E6,stroke:#1E90FF
    classDef module fill:#FFE4B5,stroke:#DAA520
    classDef db fill:#98FB98,stroke:#228B22
    classDef queue fill:#FFDAB9,stroke:#FF8C00
    classDef external fill:#D3D3D3,stroke:#696969
```
