# 1panel-dev/maxkb architecture

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

- Interactive diagram: https://gitdiagram.com/1panel-dev/maxkb
- Repository: https://github.com/1panel-dev/maxkb

## Overview

MaxKB is an enterprise agent platform combining knowledge-grounded chat, workflow orchestration, model integrations, and MCP tool use. The typical user configures an application and knowledge sources, then exposes it for chat or business-system integration; requests can use retrieval and workflow capabilities to produce multimodal responses. The tree and excerpts show the main domain stages, but not enough runtime routing to assert detailed call chains. README statements support the product-level capability links; uncertain implementation links are dashed.

Main entry points: [`apps/knowledge/serializers/common.py`](https://github.com/1panel-dev/maxkb/blob/v2/apps/knowledge/serializers/common.py) (Knowledge Management), [`apps/application/serializers/application.py`](https://github.com/1panel-dev/maxkb/blob/v2/apps/application/serializers/application.py) (Application Setup), [`apps/application/flow/step_node`](https://github.com/1panel-dev/maxkb/tree/v2/apps/application/flow/step_node) (Workflow Nodes), [`apps/application/views/application.py`](https://github.com/1panel-dev/maxkb/blob/v2/apps/application/views/application.py) (Application API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Applications &amp; Chat"]
  node_web["Web Interface<br/>[main.ts]"]
  node_app_api["Application API<br/>[application.py]"]
  node_app_config["Application Setup<br/>[application.py]"]
  node_app_record[("Application Model<br/>[application.py]")]
  node_chat_api["Chat API<br/>[chat.py]"]
  node_chat_pipeline["Chat Pipeline"]
end

subgraph group_knowledge["Knowledge RAG"]
  node_knowledge_api["Knowledge API<br/>[paragraph.py]"]
  node_knowledge_manage["Knowledge Management<br/>[common.py]"]
  node_documents[("Document &amp; Paragraphs<br/>[paragraph.py]")]
  node_knowledge_models[("Knowledge Records<br/>[knowledge.py]")]
  node_ingest_tasks["Ingestion Tasks<br/>[handler.py]"]
  node_search["Knowledge Search<br/>[search.py]"]
end

subgraph group_workflow["Agent Workflows"]
  node_workflow_engine["Workflow Engine<br/>[workflow_manage.py]"]
  node_workflow_nodes["Workflow Nodes"]
  node_flow_tools["Tool Library<br/>[tools.py]"]
  node_mcp["MCP Tool Use<br/>[client.py]"]
end

subgraph group_models["Models &amp; Tools"]
  node_model_providers["Model Providers"]
  node_provider_impl["Provider Integrations"]
end

subgraph group_shared["Shared Services"]
  node_config["Runtime Configuration<br/>[conf.py]"]
  node_permissions["Permissions"]
  node_exceptions["API Exceptions<br/>[app_exception.py]"]
  node_common_utils["Common Utilities<br/>[common.py]"]
  node_fork["Web Fetching<br/>[fork.py]"]
  node_logging["Logging<br/>[logger.py]"]
end

node_user(("User / Integrator"))
node_postgres[("PostgreSQL + pgvector")]

node_user -.->|"uses"| node_web
node_web -.->|"configures"| node_app_api
node_user -.->|"asks questions"| node_chat_api
node_app_api -->|"manages"| node_app_config
node_app_config -->|"persists"| node_app_record
node_chat_api -.->|"runs chat"| node_chat_pipeline
node_knowledge_api -->|"delegates"| node_knowledge_manage
node_knowledge_manage -->|"fetches URLs"| node_fork
node_knowledge_manage -.->|"manages paragraphs"| node_documents
node_documents -.->|"stores knowledge"| node_knowledge_models
node_documents -->|"queues embedding"| node_ingest_tasks
node_ingest_tasks -.->|"stores vectors"| node_postgres
node_chat_pipeline -.->|"retrieves context"| node_search
node_search -.->|"searches vectors"| node_postgres
node_app_config -->|"configures workflow"| node_workflow_engine
node_workflow_engine -.->|"orchestrates"| node_workflow_nodes
node_workflow_nodes -.->|"uses tools"| node_flow_tools
node_workflow_nodes -.->|"uses MCP"| node_mcp
node_chat_pipeline -.->|"generates responses"| node_model_providers
node_workflow_nodes -.->|"calls models"| node_model_providers
node_model_providers -->|"provides integrations"| node_provider_impl
node_app_config -.->|"selects knowledge"| node_knowledge_manage
node_app_api -->|"checks access"| node_permissions
node_knowledge_manage -->|"uses search"| node_search
node_knowledge_manage -->|"raises errors"| node_exceptions
node_app_config -->|"uses utilities"| node_common_utils
node_config -->|"configures logging"| node_logging

click node_web "https://github.com/1panel-dev/maxkb/blob/v2/ui/src/main.ts"
click node_app_api "https://github.com/1panel-dev/maxkb/blob/v2/apps/application/views/application.py"
click node_app_config "https://github.com/1panel-dev/maxkb/blob/v2/apps/application/serializers/application.py"
click node_app_record "https://github.com/1panel-dev/maxkb/blob/v2/apps/application/models/application.py"
click node_chat_api "https://github.com/1panel-dev/maxkb/blob/v2/apps/chat/views/chat.py"
click node_chat_pipeline "https://github.com/1panel-dev/maxkb/blob/v2/apps/application/chat_pipeline/I_base_chat_pipeline.py"
click node_knowledge_api "https://github.com/1panel-dev/maxkb/blob/v2/apps/knowledge/views/paragraph.py"
click node_knowledge_manage "https://github.com/1panel-dev/maxkb/blob/v2/apps/knowledge/serializers/common.py"
click node_documents "https://github.com/1panel-dev/maxkb/blob/v2/apps/knowledge/serializers/paragraph.py"
click node_knowledge_models "https://github.com/1panel-dev/maxkb/blob/v2/apps/knowledge/models/knowledge.py"
click node_ingest_tasks "https://github.com/1panel-dev/maxkb/blob/v2/apps/knowledge/task/handler.py"
click node_search "https://github.com/1panel-dev/maxkb/blob/v2/apps/common/db/search.py"
click node_workflow_engine "https://github.com/1panel-dev/maxkb/blob/v2/apps/application/flow/workflow_manage.py"
click node_workflow_nodes "https://github.com/1panel-dev/maxkb/tree/v2/apps/application/flow/step_node"
click node_flow_tools "https://github.com/1panel-dev/maxkb/blob/v2/apps/application/flow/tools.py"
click node_mcp "https://github.com/1panel-dev/maxkb/blob/v2/apps/common/mcp/client.py"
click node_model_providers "https://github.com/1panel-dev/maxkb/blob/v2/apps/models_provider/base_model_provider.py"
click node_provider_impl "https://github.com/1panel-dev/maxkb/blob/v2/apps/models_provider/impl/volcanic_engine_model_provider/volcanic_engine_model_provider.py"
click node_config "https://github.com/1panel-dev/maxkb/blob/v2/apps/maxkb/conf.py"
click node_permissions "https://github.com/1panel-dev/maxkb/blob/v2/apps/common/constants/permission_constants.py"
click node_exceptions "https://github.com/1panel-dev/maxkb/blob/v2/apps/common/exception/app_exception.py"
click node_common_utils "https://github.com/1panel-dev/maxkb/blob/v2/apps/common/utils/common.py"
click node_fork "https://github.com/1panel-dev/maxkb/blob/v2/apps/common/utils/fork.py"
click node_logging "https://github.com/1panel-dev/maxkb/blob/v2/apps/common/utils/logger.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_web,node_app_api,node_app_config,node_app_record,node_chat_api,node_chat_pipeline,node_user toneBlue
class node_knowledge_api,node_knowledge_manage,node_documents,node_knowledge_models,node_ingest_tasks,node_search,node_postgres toneAmber
class node_workflow_engine,node_workflow_nodes,node_flow_tools,node_mcp toneMint
class node_model_providers,node_provider_impl toneRose
class node_config,node_permissions,node_exceptions,node_common_utils,node_fork,node_logging toneIndigo
```

## Components

### Applications & Chat

- [Web Interface](https://github.com/1panel-dev/maxkb/blob/v2/ui/src/main.ts): `ui/src/main.ts`
- [Application API](https://github.com/1panel-dev/maxkb/blob/v2/apps/application/views/application.py): `apps/application/views/application.py`
- [Application Setup](https://github.com/1panel-dev/maxkb/blob/v2/apps/application/serializers/application.py): `apps/application/serializers/application.py`
- [Application Model](https://github.com/1panel-dev/maxkb/blob/v2/apps/application/models/application.py): `apps/application/models/application.py`
- [Chat API](https://github.com/1panel-dev/maxkb/blob/v2/apps/chat/views/chat.py): `apps/chat/views/chat.py`
- [Chat Pipeline](https://github.com/1panel-dev/maxkb/blob/v2/apps/application/chat_pipeline/I_base_chat_pipeline.py): `apps/application/chat_pipeline/I_base_chat_pipeline.py`

### Knowledge RAG

- [Knowledge API](https://github.com/1panel-dev/maxkb/blob/v2/apps/knowledge/views/paragraph.py): `apps/knowledge/views/paragraph.py`
- [Knowledge Management](https://github.com/1panel-dev/maxkb/blob/v2/apps/knowledge/serializers/common.py): `apps/knowledge/serializers/common.py`
- [Document & Paragraphs](https://github.com/1panel-dev/maxkb/blob/v2/apps/knowledge/serializers/paragraph.py): `apps/knowledge/serializers/paragraph.py`
- [Knowledge Records](https://github.com/1panel-dev/maxkb/blob/v2/apps/knowledge/models/knowledge.py): `apps/knowledge/models/knowledge.py`
- [Ingestion Tasks](https://github.com/1panel-dev/maxkb/blob/v2/apps/knowledge/task/handler.py): `apps/knowledge/task/handler.py`
- [Knowledge Search](https://github.com/1panel-dev/maxkb/blob/v2/apps/common/db/search.py): `apps/common/db/search.py`

### Agent Workflows

- [Workflow Engine](https://github.com/1panel-dev/maxkb/blob/v2/apps/application/flow/workflow_manage.py): `apps/application/flow/workflow_manage.py`
- [Workflow Nodes](https://github.com/1panel-dev/maxkb/tree/v2/apps/application/flow/step_node): `apps/application/flow/step_node`
- [Tool Library](https://github.com/1panel-dev/maxkb/blob/v2/apps/application/flow/tools.py): `apps/application/flow/tools.py`
- [MCP Tool Use](https://github.com/1panel-dev/maxkb/blob/v2/apps/common/mcp/client.py): `apps/common/mcp/client.py`

### Models & Tools

- [Model Providers](https://github.com/1panel-dev/maxkb/blob/v2/apps/models_provider/base_model_provider.py): `apps/models_provider/base_model_provider.py`
- [Provider Integrations](https://github.com/1panel-dev/maxkb/blob/v2/apps/models_provider/impl/volcanic_engine_model_provider/volcanic_engine_model_provider.py): `apps/models_provider/impl/volcanic_engine_model_provider/volcanic_engine_model_provider.py`

### Shared Services

- [Runtime Configuration](https://github.com/1panel-dev/maxkb/blob/v2/apps/maxkb/conf.py): `apps/maxkb/conf.py`
- [Permissions](https://github.com/1panel-dev/maxkb/blob/v2/apps/common/constants/permission_constants.py): `apps/common/constants/permission_constants.py`
- [API Exceptions](https://github.com/1panel-dev/maxkb/blob/v2/apps/common/exception/app_exception.py): `apps/common/exception/app_exception.py`
- [Common Utilities](https://github.com/1panel-dev/maxkb/blob/v2/apps/common/utils/common.py): `apps/common/utils/common.py`
- [Web Fetching](https://github.com/1panel-dev/maxkb/blob/v2/apps/common/utils/fork.py): `apps/common/utils/fork.py`
- [Logging](https://github.com/1panel-dev/maxkb/blob/v2/apps/common/utils/logger.py): `apps/common/utils/logger.py`

### Other components

- **User / Integrator**
- **PostgreSQL + pgvector**

## Connections

- User / Integrator → Web Interface: uses (evidence: `README.md`)
- Web Interface → Application API: configures
- User / Integrator → Chat API: asks questions (evidence: `README.md`)
- Application API → Application Setup: manages (evidence: `apps/application/views/application.py`)
- Application Setup → Application Model: persists (evidence: `apps/application/serializers/application.py`)
- Chat API → Chat Pipeline: runs chat
- Knowledge API → Knowledge Management: delegates (evidence: `apps/knowledge/views/paragraph.py`)
- Knowledge Management → Web Fetching: fetches URLs (evidence: `apps/knowledge/serializers/common.py`)
- Knowledge Management → Document & Paragraphs: manages paragraphs (evidence: `apps/knowledge/serializers/paragraph.py`)
- Document & Paragraphs → Knowledge Records: stores knowledge
- Document & Paragraphs → Ingestion Tasks: queues embedding (evidence: `apps/knowledge/serializers/paragraph.py`)
- Ingestion Tasks → PostgreSQL + pgvector: stores vectors (evidence: `README.md`)
- Chat Pipeline → Knowledge Search: retrieves context (evidence: `README.md`)
- Knowledge Search → PostgreSQL + pgvector: searches vectors (evidence: `README.md`)
- Application Setup → Workflow Engine: configures workflow (evidence: `apps/application/serializers/application.py`)
- Workflow Engine → Workflow Nodes: orchestrates (evidence: `README.md`)
- Workflow Nodes → Tool Library: uses tools (evidence: `README.md`)
- Workflow Nodes → MCP Tool Use: uses MCP (evidence: `README.md`)
- Chat Pipeline → Model Providers: generates responses (evidence: `README.md`)
- Workflow Nodes → Model Providers: calls models (evidence: `README.md`)
- Model Providers → Provider Integrations: provides integrations (evidence: `apps/models_provider/impl/volcanic_engine_model_provider/volcanic_engine_model_provider.py`)
- Application Setup → Knowledge Management: selects knowledge (evidence: `apps/application/serializers/application.py`)
- Application API → Permissions: checks access (evidence: `apps/application/views/application.py`)
- Knowledge Management → Knowledge Search: uses search (evidence: `apps/knowledge/serializers/common.py`)
- Knowledge Management → API Exceptions: raises errors (evidence: `apps/knowledge/serializers/common.py`)
- Application Setup → Common Utilities: uses utilities (evidence: `apps/application/serializers/application.py`)
- Runtime Configuration → Logging: configures logging (evidence: `apps/maxkb/conf.py`)
