Overview

Relevant source files

• .dockerignore
• .github/workflows/build-and-push-python-pg.yml
• .github/workflows/build-and-push-vector-model.yml
• .github/workflows/build-and-push.yml
• apps/common/utils/tool_code.py
• installer/Dockerfile
• installer/Dockerfile-base
• installer/Dockerfile-vector-model
• installer/install_model_bert_base_cased.py
• installer/sandbox.c
• pyproject.toml

Purpose and Scope

This document provides an overview of MaxKB, an open-source enterprise-grade AI assistant platform that integrates Retrieval-Augmented Generation (RAG) pipelines with robust workflow capabilities. MaxKB is designed to solve high technical barriers, deployment costs, and long iteration cycles faced by enterprises implementing AI solutions.

This overview covers the high-level system architecture, core components, key features, and technology stack. For detailed information about specific subsystems, see the following related pages:

• For authentication and permission systems, see Authentication and Authorization System
• For AI chat functionality, see AI Chat System
• For workflow design and execution, see Workflow Engine
• For knowledge base management, see Knowledge Base System

System Architecture

MaxKB implements a layered architecture with clear separation of concerns across client, API gateway, application logic, processing, AI integration, and data layers.

Overall Architecture

Sources: installer/Dockerfile1-57 pyproject.toml1-87 apps/common/utils/tool_code.py39-277

Core Components

Django Application Structure

MaxKB is organized into several Django apps, each handling a specific domain:

Key Code Entities

Component	Location	Primary Responsibility
ToolExecutor	apps/common/utils/tool_code.py	Executes custom tool code in sandboxed environment
sandbox.so	installer/sandbox.c	C library for system call interception and security
CONFIG	maxkb/const.py	Global configuration management
WorkflowManage	Workflow engine	Orchestrates node-based workflow execution
PipelineManage	Pipeline system	Alternative execution model for chat flows
LLM Providers	langchain-* packages	Integrations with 15+ LLM services

Sources: apps/common/utils/tool_code.py39-277 installer/sandbox.c1-592 pyproject.toml23-62

Security and Execution Architecture

MaxKB implements a sophisticated security model for code execution:

The sandbox implementation (sandbox.c) intercepts system calls via LD_PRELOAD to enforce:

• Network access restrictions via IP/CIDR and domain blacklists
• Subprocess creation control (configurable via SANDBOX_PYTHON_ALLOW_SUBPROCESS)
• Dynamic library loading restrictions to allowed paths only
• System call filtering (configurable via SANDBOX_PYTHON_ALLOW_SYSCALL)

Sources: installer/sandbox.c1-592 apps/common/utils/tool_code.py26-90 installer/Dockerfile1-57

Key Features

MaxKB provides comprehensive AI assistant capabilities through several integrated systems:

Feature Category	Implementation	Key Code Components
RAG Pipeline	Document ingestion, vectorization, similarity search	sentence-transformers, pgvector, apps/dataset/
Workflow Engine	Node-based DAG execution with streaming support	langgraph, WorkflowManage, workflow nodes
Secure Code Execution	Sandboxed tool execution with resource limits	ToolExecutor, sandbox.c, LD_PRELOAD
MCP Integration	Model Context Protocol for tool interoperability	langchain-mcp-adapters, MCP server config
Multi-LLM Support	15+ LLM provider integrations	langchain-openai, langchain-anthropic, qianfan, zhipuai
Multi-Tenant System	Workspace-based resource isolation	RBAC system, workspace management

RAG (Retrieval-Augmented Generation)

MaxKB implements a complete RAG pipeline through the knowledge base system:

• Document Processing: Multi-format support via pymupdf (PDF), python-docx (Word), openpyxl (Excel), beautifulsoup4 (HTML)
• Vectorization: Local embedding generation using sentence-transformers at version 5.0.0
• Vector Storage: PostgreSQL with pgvector extension for efficient similarity search
• Text Splitting: Configurable chunking strategies for optimal retrieval
• Reranking: Optional reranking models for improved search relevance
• Web Crawling: Automated web content synchronization via beautifulsoup4

Workflow and Pipeline Systems

MaxKB provides two complementary execution models:

• Workflow System: Graph-based execution using langgraph for complex multi-step flows
• Pipeline System: Linear step-based execution for simpler chat interactions
• Node Types: AI Chat, Search Dataset, Question, Reply, Reranker, Intent Classify, Image Recognition, TTS/STT
• Streaming Support: Real-time response streaming for all execution modes
• Context Management: Automatic context assembly and variable passing between nodes

Secure Tool Execution

The ToolExecutor class (apps/common/utils/tool_code.py) provides sandboxed Python code execution:

• Sandbox Library: sandbox.c compiled as sandbox.so and loaded via LD_PRELOAD
• Network Filtering: Configurable IP/CIDR and domain blacklists (SANDBOX_PYTHON_BANNED_HOSTS)
• Resource Limits: CPU cores (SANDBOX_PYTHON_PROCESS_LIMIT_CPU_CORES), memory (SANDBOX_PYTHON_PROCESS_LIMIT_MEM_MB), timeout
• Subprocess Control: Optional subprocess creation restrictions
• System Call Filtering: Selective system call interception for security
• Package Isolation: Restricted Python package paths (SANDBOX_PYTHON_PACKAGE_PATHS)

Model Context Protocol (MCP)

MaxKB integrates MCP for standardized tool interaction:

• Custom MCP Tools: Convert Python functions to MCP servers via ToolExecutor.get_tool_mcp_config()
• Application MCP: Expose MaxKB applications as MCP endpoints
• Transport Support: stdio and streamable_http transports
• LangChain Integration: Via langchain-mcp-adapters package
• Dynamic Tool Generation: Automatic MCP tool schema generation from Python code

LLM Provider Support

MaxKB integrates with 15+ LLM providers through dedicated adapters:

Provider Type	Providers	Integration Package
Western LLMs	OpenAI, Anthropic, Google Gemini, AWS Bedrock, Cohere	langchain-openai, langchain-anthropic, langchain-google-genai, langchain-aws
Chinese LLMs	Baidu Qianfan, Zhipu AI, Volcengine, Tencent Cloud, Alibaba Qwen, DeepSeek	qianfan, zhipuai, volcengine-python-sdk, tencentcloud-sdk-python, dashscope, langchain-deepseek
Local Models	Ollama, Xinference	langchain-ollama, xinference-client
Embedding Models	HuggingFace, Local Transformers	langchain-huggingface, sentence-transformers

Sources: pyproject.toml23-62 apps/common/utils/tool_code.py92-277 installer/sandbox.c26-592

Technology Stack

MaxKB is built on a modern, scalable technology stack designed for enterprise deployment:

Core Technologies

Component	Technology	Version	Purpose
Frontend	Vue.js	3.x	Reactive user interface
Backend	Django	5.2.4	Web framework and APIs
Database	PostgreSQL	Latest	Primary data storage
Vector DB	pgvector	Latest	Embedding storage and search
Cache	Redis	Latest	Session and result caching
Task Queue	Celery	5.5.3	Asynchronous task processing
AI Framework	LangChain	Multiple versions	LLM integration and workflows
ML Library	PyTorch	2.7.1	Deep learning operations
Embeddings	Sentence Transformers	5.0.0	Text vectorization

Deployment & Operations

MaxKB supports multiple deployment scenarios:

• Docker Deployment: Single-command deployment with docker run
• Process Management: gunicorn for production WSGI serving
• Logging: Comprehensive logging system via apps/maxkb/settings/logging.py12-126
• Configuration: Environment-based configuration via apps/maxkb/const.py16-22
• Monitoring: Built-in system monitoring and health checks

Sources: README.md52-56 pyproject.toml10-42 pyproject.toml72-76 apps/maxkb/settings/logging.py1-126