# aixp-labs/soulbot architecture

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

- Interactive diagram: https://gitdiagram.com/aixp-labs/soulbot
- Repository: https://github.com/aixp-labs/soulbot

## Overview

SoulBot is an AI-agent framework whose main workflow takes a user message through a CLI, web/API, or Telegram entry point, runs it in an agent and session context, routes blueprint-defined work to tools or an LLM, and returns a response, optionally as a stream. Its documented product branches include AISOP execution, AIAP/AISP capabilities, multi-agent workflows, scheduling, and observability. The README supplies several runtime relationships; unsampled implementation details are represented only where the tree supports a component, not as inferred call chains.

Main entry points: [`src/soulbot/runners/runner.py`](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/runners/runner.py) (Runner), [`src/soulbot/agents/llm_agent.py`](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/agents/llm_agent.py) (Agent Tree), [`src/soulbot/sessions/base_session_service.py`](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/sessions/base_session_service.py) (Session Service), [`src/soulbot/aisop/runtime.py`](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/aisop/runtime.py) (AISOP Executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and UI"]
  node_webui["Web Dev UI<br/>[ChatView.vue]"]
  node_apihelper["API Client<br/>[useApi.ts]"]
  node_server["API Server<br/>[api_server.py]"]
  node_cli["CLI<br/>[cli.py]"]
  node_telegram["Telegram Bot<br/>[telegram.py]"]
end

subgraph group_runtime["Agent Runtime"]
  node_runner["Runner<br/>[runner.py]"]
  node_agent["Agent Tree<br/>[llm_agent.py]"]
  node_event["Interaction Events<br/>[event.py]"]
  node_eventbus["Event Bus<br/>[event_bus.py]"]
  node_model["LLM Adapter<br/>[acp_llm.py]"]
  node_request["LLM Request<br/>[llm_request.py]"]
end

subgraph group_capabilities["Agent Capabilities"]
  node_aisop["AISOP Executor<br/>[runtime.py]"]
  node_packages["AIAP Packages<br/>[aiap_list.py]"]
  node_skills["AISP Skills<br/>[aisp_list.py]"]
  node_tooling["Tools<br/>[base_tool.py]"]
  node_commands["Command System<br/>[executor.py]"]
end

subgraph group_state["Conversation State"]
  node_session["Session Service"]
  node_sessiondb[("SQLite Sessions")]
  node_stateobj["Session State<br/>[state.py]"]
  node_history[("History Services")]
end

subgraph group_operations["Operations"]
  node_scheduler["Scheduling"]
  node_observability["Observability<br/>[metrics.py]"]
  node_telegramservice(("Telegram Service"))
end

node_user(("User"))
node_llmcli(("LLM CLI Process"))

node_user -->|"sends message"| node_webui
node_webui -.->|"requests API"| node_apihelper
node_apihelper -->|"calls"| node_server
node_user -->|"starts run"| node_cli
node_user -->|"sends message"| node_telegram
node_server -->|"invokes"| node_runner
node_cli -->|"invokes"| node_runner
node_telegram -->|"invokes"| node_runner
node_runner -->|"runs agent"| node_agent
node_runner -->|"uses sessions"| node_session
node_runner -->|"publishes events"| node_eventbus
node_agent -->|"builds request"| node_request
node_agent -->|"executes tools"| node_tooling
node_agent -->|"dispatches commands"| node_commands
node_agent -->|"runs blueprint"| node_aisop
node_aisop -->|"loads packages"| node_packages
node_aisop -->|"runs skills"| node_skills
node_request -->|"generates response"| node_model
node_model -->|"uses ACP"| node_llmcli
node_session -->|"persists sessions"| node_sessiondb
node_session -->|"applies state deltas"| node_stateobj
node_session -->|"stores events"| node_event
node_runner -.->|"uses history"| node_history
node_commands -->|"schedules tasks"| node_scheduler
node_scheduler -->|"runs scheduled work"| node_runner
node_eventbus -.->|"streams updates"| node_telegramservice
node_runner -.->|"records telemetry"| node_observability

click node_webui "https://github.com/aixp-labs/soulbot/blob/main/frontend/src/views/ChatView.vue"
click node_apihelper "https://github.com/aixp-labs/soulbot/blob/main/frontend/src/composables/useApi.ts"
click node_server "https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/server/api_server.py"
click node_cli "https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/cli.py"
click node_telegram "https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/connect/telegram.py"
click node_runner "https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/runners/runner.py"
click node_agent "https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/agents/llm_agent.py"
click node_event "https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/events/event.py"
click node_eventbus "https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/bus/event_bus.py"
click node_aisop "https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/aisop/runtime.py"
click node_packages "https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/templates/basic/aiap/aiap_list.py"
click node_skills "https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/templates/basic/aisp/aisp_list.py"
click node_tooling "https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/tools/base_tool.py"
click node_commands "https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/commands/executor.py"
click node_model "https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/models/acp_llm.py"
click node_request "https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/models/llm_request.py"
click node_session "https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/sessions/base_session_service.py"
click node_sessiondb "https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/sessions/database_session_service.py"
click node_stateobj "https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/sessions/state.py"
click node_history "https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/history/sqlite_history_service.py"
click node_scheduler "https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/scheduler/schedule_service.py"
click node_observability "https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/observability/metrics.py"

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_webui,node_apihelper,node_server,node_cli,node_telegram,node_user toneBlue
class node_runner,node_agent,node_event,node_eventbus,node_model,node_request toneAmber
class node_aisop,node_packages,node_skills,node_tooling,node_commands toneMint
class node_session,node_sessiondb,node_stateobj,node_history toneRose
class node_scheduler,node_observability,node_telegramservice,node_llmcli toneIndigo
```

## Components

### Entry and UI

- [Web Dev UI](https://github.com/aixp-labs/soulbot/blob/main/frontend/src/views/ChatView.vue): `frontend/src/views/ChatView.vue`
- [API Client](https://github.com/aixp-labs/soulbot/blob/main/frontend/src/composables/useApi.ts): `frontend/src/composables/useApi.ts`
- [API Server](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/server/api_server.py): `src/soulbot/server/api_server.py`
- [CLI](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/cli.py): `src/soulbot/cli.py`
- [Telegram Bot](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/connect/telegram.py): `src/soulbot/connect/telegram.py`

### Agent Runtime

- [Runner](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/runners/runner.py): `src/soulbot/runners/runner.py`
- [Agent Tree](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/agents/llm_agent.py): `src/soulbot/agents/llm_agent.py`
- [Interaction Events](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/events/event.py): `src/soulbot/events/event.py`
- [Event Bus](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/bus/event_bus.py): `src/soulbot/bus/event_bus.py`
- [LLM Adapter](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/models/acp_llm.py): `src/soulbot/models/acp_llm.py`
- [LLM Request](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/models/llm_request.py): `src/soulbot/models/llm_request.py`

### Agent Capabilities

- [AISOP Executor](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/aisop/runtime.py): `src/soulbot/aisop/runtime.py`
- [AIAP Packages](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/templates/basic/aiap/aiap_list.py): `src/soulbot/templates/basic/aiap/aiap_list.py`
- [AISP Skills](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/templates/basic/aisp/aisp_list.py): `src/soulbot/templates/basic/aisp/aisp_list.py`
- [Tools](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/tools/base_tool.py): `src/soulbot/tools/base_tool.py`
- [Command System](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/commands/executor.py): `src/soulbot/commands/executor.py`

### Conversation State

- [Session Service](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/sessions/base_session_service.py): `src/soulbot/sessions/base_session_service.py`
- [SQLite Sessions](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/sessions/database_session_service.py): `src/soulbot/sessions/database_session_service.py`
- [Session State](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/sessions/state.py): `src/soulbot/sessions/state.py`
- [History Services](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/history/sqlite_history_service.py): `src/soulbot/history/sqlite_history_service.py`

### Operations

- [Scheduling](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/scheduler/schedule_service.py): `src/soulbot/scheduler/schedule_service.py`
- [Observability](https://github.com/aixp-labs/soulbot/blob/main/src/soulbot/observability/metrics.py): `src/soulbot/observability/metrics.py`
- **Telegram Service**

### Other components

- **User**
- **LLM CLI Process**

## Connections

- User → Web Dev UI: sends message (evidence: `README.md`)
- Web Dev UI → API Client: requests API
- API Client → API Server: calls (evidence: `frontend/src/composables/useApi.ts`)
- User → CLI: starts run (evidence: `README.md`)
- User → Telegram Bot: sends message (evidence: `README.md`)
- API Server → Runner: invokes (evidence: `README.md`)
- CLI → Runner: invokes (evidence: `README.md`)
- Telegram Bot → Runner: invokes (evidence: `README.md`)
- Runner → Agent Tree: runs agent (evidence: `README.md`)
- Runner → Session Service: uses sessions (evidence: `README.md`)
- Runner → Event Bus: publishes events (evidence: `README.md`)
- Agent Tree → LLM Request: builds request (evidence: `src/soulbot/agents/llm_agent.py`)
- Agent Tree → Tools: executes tools (evidence: `src/soulbot/agents/llm_agent.py`)
- Agent Tree → Command System: dispatches commands (evidence: `src/soulbot/agents/llm_agent.py`)
- Agent Tree → AISOP Executor: runs blueprint (evidence: `README.md`)
- AISOP Executor → AIAP Packages: loads packages (evidence: `README.md`)
- AISOP Executor → AISP Skills: runs skills (evidence: `README.md`)
- LLM Request → LLM Adapter: generates response (evidence: `README.md`)
- LLM Adapter → LLM CLI Process: uses ACP (evidence: `README.md`)
- Session Service → SQLite Sessions: persists sessions (evidence: `src/soulbot/sessions/database_session_service.py`)
- Session Service → Session State: applies state deltas (evidence: `src/soulbot/sessions/base_session_service.py`)
- Session Service → Interaction Events: stores events (evidence: `src/soulbot/sessions/base_session_service.py`)
- Runner → History Services: uses history
- Command System → Scheduling: schedules tasks (evidence: `src/soulbot/scheduler/schedule_service.py`)
- Scheduling → Runner: runs scheduled work (evidence: `src/soulbot/scheduler/schedule_service.py`)
- Event Bus → Telegram Service: streams updates
- Runner → Observability: records telemetry