# mai-with-u/maibot architecture

> Architecture diagram of the GitHub repository mai-with-u/maibot, 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/mai-with-u/maibot
- Repository: https://github.com/mai-with-u/maibot

## Overview

MaiBot is a conversational, LLM-based agent designed for human-like interaction in group chats. A typical interaction arrives through a messaging platform, is managed as a chat session, and is considered by the reasoning engine, which can use prompts, tools, and model services before sending a reply back through platform I/O. The repository also includes a WebUI for administration and distinct memory, plugin, image/emoji, and MCP capabilities. The graph emphasizes documented or indexed relationships; several subsystem links remain unverified because their implementation was not excerpted.

Main entry points: [`src/maisaka/reasoning_engine.py`](https://github.com/mai-with-u/maibot/blob/main/src/maisaka/reasoning_engine.py) (Reasoning engine), [`src/main.py`](https://github.com/mai-with-u/maibot/blob/main/src/main.py) (Application startup), [`src/common/database/database.py`](https://github.com/mai-with-u/maibot/blob/main/src/common/database/database.py) (Application database), [`src/chat/message_receive/chat_manager.py`](https://github.com/mai-with-u/maibot/blob/main/src/chat/message_receive/chat_manager.py) (Chat sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Conversation runtime"]
  node_main["Application startup<br/>[main.py]"]
  node_chat_manager["Chat sessions<br/>[chat_manager.py]"]
  node_platform_io["Platform I/O<br/>[manager.py]"]
end

subgraph group_intelligence["Reasoning and models"]
  node_reasoning["Reasoning engine"]
  node_prompts["Prompt management<br/>[prompt_manager.py]"]
  node_llm_service["LLM service<br/>[llm_service.py]"]
  node_llm_models["Model clients"]
  node_tool_schema["Tool definitions<br/>[tool_option.py]"]
end

subgraph group_memory["Memory and media"]
  node_database[("Application database<br/>[database.py]")]
  node_db_models["Stored data models<br/>[database_model.py]"]
  node_memorix["Memory ingestion<br/>[ingest_service.py]"]
  node_memory_search["Memory retrieval"]
  node_image_manager["Image understanding<br/>[image_manager.py]"]
  node_emoji_manager["Emoji library<br/>[emoji_manager.py]"]
end

subgraph group_extensions["Extensions"]
  node_plugin_runtime["Plugin runtime"]
  node_mcp["MCP services<br/>[manager.py]"]
end

subgraph group_operations["Administration"]
  node_webui["WebUI API<br/>[routes.py]"]
  node_dashboard["Dashboard interface<br/>[router.tsx]"]
  node_config["Configuration<br/>[config.py]"]
end

node_user(("Chat participants"))
node_platform(("Messaging platform"))

node_user -->|"sends messages"| node_platform
node_platform -.->|"delivers events"| node_platform_io
node_platform_io -->|"routes messages"| node_chat_manager
node_chat_manager -.->|"message handling"| node_reasoning
node_reasoning -.->|"uses prompts"| node_prompts
node_reasoning -.->|"requests generation"| node_llm_service
node_llm_service -->|"forwards requests"| node_llm_models
node_reasoning -.->|"handles tool calls"| node_tool_schema
node_reasoning -.->|"sends replies"| node_platform_io
node_main -->|"starts service"| node_chat_manager
node_main -->|"starts service"| node_webui
node_main -->|"integrates plugins"| node_plugin_runtime
node_main -->|"starts service"| node_mcp
node_main -->|"starts host"| node_memorix
node_memorix -->|"stores memories"| node_database
node_memory_search -.->|"retrieves records"| node_database
node_image_manager -->|"stores image records"| node_database
node_emoji_manager -->|"stores emoji records"| node_database
node_database -->|"creates schema"| node_db_models
node_dashboard -.->|"uses API"| node_webui
node_webui -.->|"serves configuration"| node_config
node_plugin_runtime -.->|"extends agent"| node_reasoning

click node_main "https://github.com/mai-with-u/maibot/blob/main/src/main.py"
click node_chat_manager "https://github.com/mai-with-u/maibot/blob/main/src/chat/message_receive/chat_manager.py"
click node_platform_io "https://github.com/mai-with-u/maibot/blob/main/src/platform_io/manager.py"
click node_reasoning "https://github.com/mai-with-u/maibot/blob/main/src/maisaka/reasoning_engine.py"
click node_prompts "https://github.com/mai-with-u/maibot/blob/main/src/prompt/prompt_manager.py"
click node_llm_service "https://github.com/mai-with-u/maibot/blob/main/src/services/llm_service.py"
click node_llm_models "https://github.com/mai-with-u/maibot/tree/main/src/llm_models/model_client"
click node_tool_schema "https://github.com/mai-with-u/maibot/blob/main/src/llm_models/payload_content/tool_option.py"
click node_database "https://github.com/mai-with-u/maibot/blob/main/src/common/database/database.py"
click node_db_models "https://github.com/mai-with-u/maibot/blob/main/src/common/database/database_model.py"
click node_memorix "https://github.com/mai-with-u/maibot/blob/main/src/A_memorix/core/runtime/services/ingest_service.py"
click node_memory_search "https://github.com/mai-with-u/maibot/blob/main/src/A_memorix/core/utils/retrieval_tuning_manager.py"
click node_image_manager "https://github.com/mai-with-u/maibot/blob/main/src/chat/image_system/image_manager.py"
click node_emoji_manager "https://github.com/mai-with-u/maibot/blob/main/src/emoji_system/emoji_manager.py"
click node_plugin_runtime "https://github.com/mai-with-u/maibot/blob/main/src/plugin_runtime/dependency_pipeline.py"
click node_mcp "https://github.com/mai-with-u/maibot/blob/main/src/mcp_module/manager.py"
click node_webui "https://github.com/mai-with-u/maibot/blob/main/src/webui/routes.py"
click node_dashboard "https://github.com/mai-with-u/maibot/blob/main/dashboard/src/router.tsx"
click node_config "https://github.com/mai-with-u/maibot/blob/main/src/config/config.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_main,node_chat_manager,node_platform_io toneBlue
class node_reasoning,node_prompts,node_llm_service,node_llm_models,node_tool_schema toneAmber
class node_database,node_db_models,node_memorix,node_memory_search,node_image_manager,node_emoji_manager toneMint
class node_plugin_runtime,node_mcp toneRose
class node_webui,node_dashboard,node_config,node_user,node_platform toneIndigo
```

## Components

### Conversation runtime

- [Application startup](https://github.com/mai-with-u/maibot/blob/main/src/main.py): `src/main.py`
- [Chat sessions](https://github.com/mai-with-u/maibot/blob/main/src/chat/message_receive/chat_manager.py): `src/chat/message_receive/chat_manager.py`
- [Platform I/O](https://github.com/mai-with-u/maibot/blob/main/src/platform_io/manager.py): `src/platform_io/manager.py`

### Reasoning and models

- [Reasoning engine](https://github.com/mai-with-u/maibot/blob/main/src/maisaka/reasoning_engine.py): `src/maisaka/reasoning_engine.py`
- [Prompt management](https://github.com/mai-with-u/maibot/blob/main/src/prompt/prompt_manager.py): `src/prompt/prompt_manager.py`
- [LLM service](https://github.com/mai-with-u/maibot/blob/main/src/services/llm_service.py): `src/services/llm_service.py`
- [Model clients](https://github.com/mai-with-u/maibot/tree/main/src/llm_models/model_client): `src/llm_models/model_client`
- [Tool definitions](https://github.com/mai-with-u/maibot/blob/main/src/llm_models/payload_content/tool_option.py): `src/llm_models/payload_content/tool_option.py`

### Memory and media

- [Application database](https://github.com/mai-with-u/maibot/blob/main/src/common/database/database.py): `src/common/database/database.py`
- [Stored data models](https://github.com/mai-with-u/maibot/blob/main/src/common/database/database_model.py): `src/common/database/database_model.py`
- [Memory ingestion](https://github.com/mai-with-u/maibot/blob/main/src/A_memorix/core/runtime/services/ingest_service.py): `src/A_memorix/core/runtime/services/ingest_service.py`
- [Memory retrieval](https://github.com/mai-with-u/maibot/blob/main/src/A_memorix/core/utils/retrieval_tuning_manager.py): `src/A_memorix/core/utils/retrieval_tuning_manager.py`
- [Image understanding](https://github.com/mai-with-u/maibot/blob/main/src/chat/image_system/image_manager.py): `src/chat/image_system/image_manager.py`
- [Emoji library](https://github.com/mai-with-u/maibot/blob/main/src/emoji_system/emoji_manager.py): `src/emoji_system/emoji_manager.py`

### Extensions

- [Plugin runtime](https://github.com/mai-with-u/maibot/blob/main/src/plugin_runtime/dependency_pipeline.py): `src/plugin_runtime/dependency_pipeline.py`
- [MCP services](https://github.com/mai-with-u/maibot/blob/main/src/mcp_module/manager.py): `src/mcp_module/manager.py`

### Administration

- [WebUI API](https://github.com/mai-with-u/maibot/blob/main/src/webui/routes.py): `src/webui/routes.py`
- [Dashboard interface](https://github.com/mai-with-u/maibot/blob/main/dashboard/src/router.tsx): `dashboard/src/router.tsx`
- [Configuration](https://github.com/mai-with-u/maibot/blob/main/src/config/config.py): `src/config/config.py`

### Other components

- **Chat participants**
- **Messaging platform**

## Connections

- Chat participants → Messaging platform: sends messages
- Messaging platform → Platform I/O: delivers events
- Platform I/O → Chat sessions: routes messages (evidence: `src/platform_io/manager.py`)
- Chat sessions → Reasoning engine: message handling
- Reasoning engine → Prompt management: uses prompts
- Reasoning engine → LLM service: requests generation
- LLM service → Model clients: forwards requests (evidence: `src/services/llm_service.py`)
- Reasoning engine → Tool definitions: handles tool calls (evidence: `src/maisaka/reasoning_engine.py`)
- Reasoning engine → Platform I/O: sends replies
- Application startup → Chat sessions: starts service (evidence: `src/main.py`)
- Application startup → WebUI API: starts service (evidence: `src/main.py`)
- Application startup → Plugin runtime: integrates plugins (evidence: `src/main.py`)
- Application startup → MCP services: starts service (evidence: `src/main.py`)
- Application startup → Memory ingestion: starts host (evidence: `src/main.py`)
- Memory ingestion → Application database: stores memories (evidence: `src/A_memorix/core/runtime/services/ingest_service.py`)
- Memory retrieval → Application database: retrieves records
- Image understanding → Application database: stores image records (evidence: `src/chat/image_system/image_manager.py`)
- Emoji library → Application database: stores emoji records (evidence: `src/emoji_system/emoji_manager.py`)
- Application database → Stored data models: creates schema (evidence: `src/common/database/database.py`)
- Dashboard interface → WebUI API: uses API
- WebUI API → Configuration: serves configuration
- Plugin runtime → Reasoning engine: extends agent