# hexabot-ai/hexabot architecture

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

- Interactive diagram: https://gitdiagram.com/hexabot-ai/hexabot
- Repository: https://github.com/hexabot-ai/hexabot

## Overview

Hexabot is an AI-enabled automation platform for authoring and running workflows across conversational channels. The principal path is workflow authoring in the visual/YAML editor, workflow management through the API, then agentic execution using actions and bindings; channel events and integrations provide conversational inputs and outputs. Major documented capabilities also include memory, MCP, and RAG. Source excerpts show selected API, editor, and RAG calls; README statements support the broader product relationships, while unsampled runtime details are not expanded.

Main entry points: [`packages/agentic/src/workflow-runner.ts`](https://github.com/hexabot-ai/hexabot/blob/main/packages/agentic/src/workflow-runner.ts) (Workflow runner), [`packages/api/src/workflow/controllers/workflow.controller.ts`](https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/workflow/controllers/workflow.controller.ts) (Workflow API), [`packages/agentic/src/step-executors`](https://github.com/hexabot-ai/hexabot/tree/main/packages/agentic/src/step-executors) (Step executors), [`packages/api/src/channel/lib/Handler.ts`](https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/channel/lib/Handler.ts) (Channel ingress and dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Workflow authoring"]
  node_editor["Visual workflow editor"]
  node_yaml["YAML editor"]
  node_graph["Workflow graph"]
  node_workflow_api["Workflow API"]
  node_workflow_data[("Workflow definitions")]
end

subgraph group_runtime["Workflow runtime"]
  node_runner["Workflow runner<br/>[workflow-runner.ts]"]
  node_compiler["Workflow compiler"]
  node_executors["Step executors"]
  node_context["Execution context<br/>[context.ts]"]
  node_actions["Action registry<br/>[actions.service.ts]"]
  node_bindings["Runtime bindings"]
end

subgraph group_conversation["Conversation channels"]
  node_channel_api["Channel ingress and dispatch<br/>[Handler.ts]"]
  node_channel_events["Channel event decoding"]
  node_web_channel["Web channel<br/>[index.channel.ts]"]
  node_messaging["Messaging actions"]
end

subgraph group_capabilities["AI and integrations"]
  node_ai_actions["AI actions<br/>[ai-base.action.ts]"]
  node_memory["Memory integration"]
  node_mcp["MCP tools"]
  node_rag["RAG content retrieval<br/>[rag.service.ts]"]
end

subgraph group_platform["Platform services"]
  node_content["CMS content<br/>[content.service.ts]"]
  node_content_store[("Content records<br/>[content.entity.ts]")]
  node_accounts[("Users and permissions<br/>[user.service.ts]")]
  node_health["Integration health<br/>[health.service.ts]"]
end

node_operator(("Workflow operator"))

node_operator -->|"authors"| node_editor
node_operator -->|"edits definitions"| node_yaml
node_editor -.->|"visualizes"| node_graph
node_yaml -->|"updates definition"| node_editor
node_editor -.->|"manages workflows"| node_workflow_api
node_workflow_api -.->|"manages"| node_workflow_data
node_workflow_api -->|"resolves bindings"| node_bindings
node_workflow_api -.->|"starts execution"| node_runner
node_runner -.->|"compiles definition"| node_compiler
node_runner -.->|"dispatches steps"| node_executors
node_executors -.->|"uses context"| node_context
node_executors -.->|"runs actions"| node_actions
node_executors -.->|"uses bindings"| node_bindings
node_operator -->|"sends messages"| node_channel_api
node_channel_api -.->|"decodes events"| node_channel_events
node_channel_api -.->|"supports channel"| node_web_channel
node_channel_api -.->|"triggers workflows"| node_runner
node_runner -.->|"dispatches actions"| node_messaging
node_runner -->|"dispatches actions"| node_ai_actions
node_runner -->|"uses memory"| node_memory
node_runner -->|"uses MCP tools"| node_mcp
node_runner -->|"retrieves content"| node_rag
node_rag -->|"uses content service"| node_content
node_rag -->|"indexes content"| node_content_store
node_workflow_api -.->|"checks access"| node_accounts
node_operator -->|"checks integrations"| node_health

click node_editor "https://github.com/hexabot-ai/hexabot/blob/main/packages/frontend/src/components/visual-editor/v4/components/main/ActionDrawer/ActionFormDrawer/useActionFormDrawerController.ts"
click node_yaml "https://github.com/hexabot-ai/hexabot/blob/main/packages/frontend/src/components/visual-editor/v4/components/yaml-editor/useYamlEditorController.ts"
click node_graph "https://github.com/hexabot-ai/hexabot/blob/main/packages/graph/src/workflow/types/workflow-node.types.ts"
click node_workflow_api "https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/workflow/controllers/workflow.controller.ts"
click node_workflow_data "https://github.com/hexabot-ai/hexabot/tree/main/packages/api/src/workflow"
click node_runner "https://github.com/hexabot-ai/hexabot/blob/main/packages/agentic/src/workflow-runner.ts"
click node_compiler "https://github.com/hexabot-ai/hexabot/blob/main/packages/agentic/src/workflow-compiler.ts"
click node_executors "https://github.com/hexabot-ai/hexabot/tree/main/packages/agentic/src/step-executors"
click node_context "https://github.com/hexabot-ai/hexabot/blob/main/packages/agentic/src/context.ts"
click node_actions "https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/actions/actions.service.ts"
click node_bindings "https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/bindings/runtime-bindings.service.ts"
click node_channel_api "https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/channel/lib/Handler.ts"
click node_channel_events "https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/channel/lib/inbound-events/channel-inbound-event-decoder.ts"
click node_web_channel "https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/extensions/channels/web/index.channel.ts"
click node_messaging "https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/extensions/actions/messaging/message-action.base.ts"
click node_ai_actions "https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/extensions/actions/ai/ai-base.action.ts"
click node_memory "https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/extensions/actions/memory/update-memory.action.ts"
click node_mcp "https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/mcp/tools/hexabot-mcp.tools.ts"
click node_rag "https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/cms/services/rag.service.ts"
click node_content "https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/cms/services/content.service.ts"
click node_content_store "https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/cms/entities/content.entity.ts"
click node_accounts "https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/user/services/user.service.ts"
click node_health "https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/health/health.service.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_editor,node_yaml,node_graph,node_workflow_api,node_workflow_data toneBlue
class node_runner,node_compiler,node_executors,node_context,node_actions,node_bindings toneAmber
class node_channel_api,node_channel_events,node_web_channel,node_messaging toneMint
class node_ai_actions,node_memory,node_mcp,node_rag toneRose
class node_content,node_content_store,node_accounts,node_health,node_operator toneIndigo
```

## Components

### Workflow authoring

- [Visual workflow editor](https://github.com/hexabot-ai/hexabot/blob/main/packages/frontend/src/components/visual-editor/v4/components/main/ActionDrawer/ActionFormDrawer/useActionFormDrawerController.ts): `packages/frontend/src/components/visual-editor/v4/components/main/ActionDrawer/ActionFormDrawer/useActionFormDrawerController.ts`
- [YAML editor](https://github.com/hexabot-ai/hexabot/blob/main/packages/frontend/src/components/visual-editor/v4/components/yaml-editor/useYamlEditorController.ts): `packages/frontend/src/components/visual-editor/v4/components/yaml-editor/useYamlEditorController.ts`
- [Workflow graph](https://github.com/hexabot-ai/hexabot/blob/main/packages/graph/src/workflow/types/workflow-node.types.ts): `packages/graph/src/workflow/types/workflow-node.types.ts`
- [Workflow API](https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/workflow/controllers/workflow.controller.ts): `packages/api/src/workflow/controllers/workflow.controller.ts`
- [Workflow definitions](https://github.com/hexabot-ai/hexabot/tree/main/packages/api/src/workflow): `packages/api/src/workflow`

### Workflow runtime

- [Workflow runner](https://github.com/hexabot-ai/hexabot/blob/main/packages/agentic/src/workflow-runner.ts): `packages/agentic/src/workflow-runner.ts`
- [Workflow compiler](https://github.com/hexabot-ai/hexabot/blob/main/packages/agentic/src/workflow-compiler.ts): `packages/agentic/src/workflow-compiler.ts`
- [Step executors](https://github.com/hexabot-ai/hexabot/tree/main/packages/agentic/src/step-executors): `packages/agentic/src/step-executors`
- [Execution context](https://github.com/hexabot-ai/hexabot/blob/main/packages/agentic/src/context.ts): `packages/agentic/src/context.ts`
- [Action registry](https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/actions/actions.service.ts): `packages/api/src/actions/actions.service.ts`
- [Runtime bindings](https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/bindings/runtime-bindings.service.ts): `packages/api/src/bindings/runtime-bindings.service.ts`

### Conversation channels

- [Channel ingress and dispatch](https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/channel/lib/Handler.ts): `packages/api/src/channel/lib/Handler.ts`
- [Channel event decoding](https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/channel/lib/inbound-events/channel-inbound-event-decoder.ts): `packages/api/src/channel/lib/inbound-events/channel-inbound-event-decoder.ts`
- [Web channel](https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/extensions/channels/web/index.channel.ts): `packages/api/src/extensions/channels/web/index.channel.ts`
- [Messaging actions](https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/extensions/actions/messaging/message-action.base.ts): `packages/api/src/extensions/actions/messaging/message-action.base.ts`

### AI and integrations

- [AI actions](https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/extensions/actions/ai/ai-base.action.ts): `packages/api/src/extensions/actions/ai/ai-base.action.ts`
- [Memory integration](https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/extensions/actions/memory/update-memory.action.ts): `packages/api/src/extensions/actions/memory/update-memory.action.ts`
- [MCP tools](https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/mcp/tools/hexabot-mcp.tools.ts): `packages/api/src/mcp/tools/hexabot-mcp.tools.ts`
- [RAG content retrieval](https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/cms/services/rag.service.ts): `packages/api/src/cms/services/rag.service.ts`

### Platform services

- [CMS content](https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/cms/services/content.service.ts): `packages/api/src/cms/services/content.service.ts`
- [Content records](https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/cms/entities/content.entity.ts): `packages/api/src/cms/entities/content.entity.ts`
- [Users and permissions](https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/user/services/user.service.ts): `packages/api/src/user/services/user.service.ts`
- [Integration health](https://github.com/hexabot-ai/hexabot/blob/main/packages/api/src/health/health.service.ts): `packages/api/src/health/health.service.ts`

### Other components

- **Workflow operator**

## Connections

- Workflow operator → Visual workflow editor: authors
- Workflow operator → YAML editor: edits definitions
- Visual workflow editor → Workflow graph: visualizes
- YAML editor → Visual workflow editor: updates definition (evidence: `packages/frontend/src/components/visual-editor/v4/components/yaml-editor/useYamlEditorController.ts`)
- Visual workflow editor → Workflow API: manages workflows
- Workflow API → Workflow definitions: manages (evidence: `packages/api/src/workflow/controllers/workflow.controller.ts`)
- Workflow API → Runtime bindings: resolves bindings (evidence: `packages/api/src/workflow/controllers/workflow.controller.ts`)
- Workflow API → Workflow runner: starts execution
- Workflow runner → Workflow compiler: compiles definition
- Workflow runner → Step executors: dispatches steps
- Step executors → Execution context: uses context
- Step executors → Action registry: runs actions
- Step executors → Runtime bindings: uses bindings
- Workflow operator → Channel ingress and dispatch: sends messages
- Channel ingress and dispatch → Channel event decoding: decodes events
- Channel ingress and dispatch → Web channel: supports channel
- Channel ingress and dispatch → Workflow runner: triggers workflows
- Workflow runner → Messaging actions: dispatches actions
- Workflow runner → AI actions: dispatches actions
- Workflow runner → Memory integration: uses memory
- Workflow runner → MCP tools: uses MCP tools
- Workflow runner → RAG content retrieval: retrieves content
- RAG content retrieval → CMS content: uses content service (evidence: `packages/api/src/cms/services/rag.service.ts`)
- RAG content retrieval → Content records: indexes content (evidence: `packages/api/src/cms/services/rag.service.ts`)
- Workflow API → Users and permissions: checks access
- Workflow operator → Integration health: checks integrations
