# https://github.com/1Panel-dev/MaxKB Project Manual

Generated at: 2026-06-22 19:11:41 UTC

## Table of Contents

- [System Overview and Architecture](#page-1)
- [Application Engine and Workflow Nodes](#page-2)
- [Knowledge Base, Tools, and Model Providers](#page-3)
- [Frontend, Deployment, and System Management](#page-4)

<a id='page-1'></a>

## System Overview and Architecture

### Related Pages

Related topics: [Application Engine and Workflow Nodes](#page-2), [Knowledge Base, Tools, and Model Providers](#page-3), [Frontend, Deployment, and System Management](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/1Panel-dev/MaxKB/blob/main/README.md)
- [ui/src/api/type/common.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/common.ts)
- [ui/src/api/type/application.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/application.ts)
- [ui/src/api/type/knowledge.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/knowledge.ts)
- [ui/src/api/knowledge/knowledge.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/knowledge/knowledge.ts)
- [ui/src/api/knowledge/document.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/knowledge/document.ts)
- [ui/src/api/knowledge/problem.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/knowledge/problem.ts)
- [ui/src/api/system-resource-management/paragraph.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-resource-management/paragraph.ts)
- [ui/src/api/system-resource-management/tool.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-resource-management/tool.ts)
- [ui/src/api/system/role.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system/role.ts)
- [ui/src/api/trigger/trigger.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/trigger/trigger.ts)
- [apps/knowledge/api/knowledge_version.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/knowledge_version.py)
- [apps/knowledge/api/termbase.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/termbase.py)
- [apps/tools/api/tool.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/tools/api/tool.py)
- [ui/src/api/shared-workspace.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/shared-workspace.ts)
</details>

# System Overview and Architecture

## Purpose and Scope

MaxKB is an open-source platform for building enterprise-grade agents. It positions itself as a unified workspace where teams can assemble large-language-model-powered applications backed by curated knowledge, external tools, and event-driven triggers. The repository is licensed under GPLv3 and is distributed as a self-hostable product.

According to the project README, the platform is built on a clearly defined technical stack:

- **Frontend:** Vue.js
- **Backend:** Python / Django
- **LLM Framework:** LangChain
- **Database:** PostgreSQL with the `pgvector` extension

Source: [README.md](https://github.com/1Panel-dev/MaxKB/blob/main/README.md)

The codebase is split into a Django backend under `apps/` and a Vue.js frontend under `ui/`. Each side mirrors the same domain model — knowledge, applications, tools, triggers, and system administration — which keeps the contract between client and server explicit and easy to evolve.

## High-Level Architecture

The system is organized as a classic three-tier application: a Vue.js single-page client, a Django REST API layer, and a PostgreSQL+pgvector data tier that stores both relational state and vector embeddings for retrieval-augmented generation (RAG).

```mermaid
flowchart TB
    subgraph Client["Vue.js Frontend (ui/)"]
        UI["Pages & Components"]
        API["api/ modules<br/>(knowledge, tool, trigger, role)"]
        Types["api/type<br/>(common, application, knowledge)"]
    end

    subgraph Server["Django Backend (apps/)"]
        KB["knowledge/ app<br/>(knowledge_version.py, termbase.py)"]
        TL["tools/ app<br/>(tool.py)"]
        TR["triggers, applications, system apps"]
    end

    subgraph Data["Data Tier"]
        PG[("PostgreSQL")]
        VEC[("pgvector embeddings")]
    end

    UI --> API
    API --> Types
    API -- "HTTP / JSON" --> Server
    KB --> PG
    KB --> VEC
    TL --> PG
    TR --> PG
```

The client never talks to the database directly. Every interaction funnels through a typed API module that issues REST calls — `get`, `post`, `put`, `del` — defined in `ui/src/request/` and consumed by domain-specific files.

## Module Breakdown

### Knowledge Domain

The knowledge layer is the most domain-rich part of the system. It manages **knowledge bases**, their **documents**, the **paragraphs** inside those documents, and the **problems** (a.k.a. Q&A pairs) that bind structured questions to evidence chunks. The frontend exposes one TypeScript module per resource: `knowledge.ts`, `document.ts`, `paragraph.ts`, and `problem.ts`. Each follows the same CRUD + paginated-list pattern.

For example, the knowledge problem API in `ui/src/api/knowledge/problem.ts` defines:

- `putProblems` — modify a problem
- `delProblems` — delete a problem
- `getDetailProblems` — fetch paragraphs linked to a problem
- `putMulAssociationProblem` — bulk-associate paragraphs to a problem

Source: [ui/src/api/knowledge/problem.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/knowledge/problem.ts)

On the server side, the Django app under `apps/knowledge/api/` mirrors the same vocabulary. `knowledge_version.py` exposes versioned workflow definitions, and `termbase.py` exposes Q&A term-base management with `TermbasePageAPI` and `TermbaseDeleteAPI`. Both files use an `APIMixin` pattern with explicit `OpenApiParameter` declarations, which means the project ships with a self-describing OpenAPI surface.

Source: [apps/knowledge/api/knowledge_version.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/knowledge_version.py)
Source: [apps/knowledge/api/termbase.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/termbase.py)

The shared data type `knowledgeData` (in `ui/src/api/type/knowledge.ts`) carries the basic shape of a knowledge base — `name`, `folder_id`, `desc`, `embedding_model_id`, and an optional list of `documents` — which is the contract reused by the create/edit forms.

Source: [ui/src/api/type/knowledge.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/knowledge.ts)

### Tools and Triggers

The tool system is split into two access scopes visible from the API: `SHARED` and `WORKSPACE`. `apps/tools/api/tool.py` documents the `ToolPageAPI` parameters, including `scope` (enum), `folder_id`, and optional filters like `name` and `user_id`.

Source: [apps/tools/api/tool.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/tools/api/tool.py)

On the frontend, `ui/src/api/system-resource-management/tool.ts` and the parallel `ui/src/api/system-shared/tool.ts` re-export the same surface under different URL prefixes, so a single component can call into either workspace-owned or system-shared tooling without changing its call signature.

Triggers follow a similar pattern. `ui/src/api/trigger/trigger.ts` defines paginated task record queries (`pageTriggerTaskRecord`), detail fetchers (`getTriggerTaskRecordDetails`), and a `postResourceTrigger` helper that creates a trigger against any resource type — applications, knowledge bases, or tools — using a `source_type` and `source_id` pair.

Source: [ui/src/api/trigger/trigger.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/trigger/trigger.ts)

### System Administration and Shared Workspace

Two concerns run across every domain: **role-based access** and **workspace sharing**. The role API in `ui/src/api/system/role.ts` manages role templates, permissions, and member assignment (`CreateMember`, `deleteRoleMember`, `saveRolePermission`).

Source: [ui/src/api/system/role.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system/role.ts)

The shared-workspace surface, declared in `ui/src/api/shared-workspace.ts`, exposes a uniform `prefix_workspace` URL segment and provides helpers like `getProblemsPage`, `getUserGroupList`, and `getUserGroupUserList` that operate on shared resources. This is the mechanism by which one workspace can hand a knowledge base, application, or tool to another.

Source: [ui/src/api/shared-workspace.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/shared-workspace.ts)

## Common Conventions

The codebase enforces a small set of conventions that recur across every API module:

| Convention | Where it appears | What it means |
|---|---|---|
| `Result<T>` wrapper | `ui/src/api/knowledge/problem.ts`, all modules | Standardized `{ code, data, message }` envelope |
| `pageRequest` | `ui/src/api/type/common.ts` | `{ current_page, page_size }` for every paginated call |
| `PageList<T>` | `ui/src/api/type/common.ts` | `{ current, size, total, records }` for paginated responses |
| `prefix` / `prefix.value` | knowledge & trigger modules | Vue `ref` holding the base URL, swappable between system/shared |
| `loading?: Ref<boolean>` | every CRUD call | Optional loading flag passed through to the HTTP client |
| `APIMixin` | `apps/knowledge/api/*.py`, `apps/tools/api/tool.py` | Server-side OpenAPI mixin combining parameters and response |

Source: [ui/src/api/type/common.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/common.ts)

The streaming chat type in `ui/src/api/type/application.ts` (`chatType`, `Chunk`) is more elaborate: it carries `buffer`, `write_ed`, `is_stop`, and a streaming `currentChunk` object, which is what makes the agent's token-by-token reply render in the UI. This is the most application-specific shape in the type system and is shared with the workflow runtime that drives the chat experience.

Source: [ui/src/api/type/application.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/application.ts)

## See Also

- Knowledge Base Management
- Application & Workflow Runtime
- Tool Integration
- Triggers & Automation
- Role and Permission Model

---

<a id='page-2'></a>

## Application Engine and Workflow Nodes

### Related Pages

Related topics: [System Overview and Architecture](#page-1), [Knowledge Base, Tools, and Model Providers](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/1Panel-dev/MaxKB/blob/main/README.md)
- [ui/src/api/system-shared/knowledge.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-shared/knowledge.ts)
- [ui/src/api/knowledge/knowledge.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/knowledge/knowledge.ts)
- [ui/src/api/system-shared/tool.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-shared/tool.ts)
- [apps/knowledge/api/knowledge_version.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/knowledge_version.py)
- [apps/tools/api/tool.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/tools/api/tool.py)
- [ui/src/api/trigger/trigger.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/trigger/trigger.ts)
- [ui/src/api/type/application.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/application.ts)
- [ui/src/api/system/role.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system/role.ts)
</details>

# Application Engine and Workflow Nodes

## Overview and Purpose

MaxKB is an open-source platform for building enterprise-grade agents, and the application engine is its central orchestration layer. According to the project README, MaxKB is equipped with a "powerful workflow engine, function library and MCP tool-use, enabling the orchestration of AI processes to meet the needs of complex business scenarios" ([README.md](https://github.com/1Panel-dev/MaxKB/blob/main/README.md)). Workflow nodes are the building blocks of these orchestrated processes: each node encapsulates a discrete capability such as knowledge retrieval, tool invocation, conditional branching, or model interaction.

The front-end mirrors this engine with a chat runtime type system that streams node outputs back to the client. The `chatType` and `Chunk` interfaces in `application.ts` describe how individual nodes contribute content, reasoning, and child-node references during a chat session ([ui/src/api/type/application.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/application.ts)). Every streaming chunk carries fields such as `node_id`, `up_node_id`, `runtime_node_id`, `child_node`, `view_type`, `node_type`, and a content/reasoning buffer, allowing the UI to reconstruct the executed workflow from streaming events.

## Workflow API Surface

The application engine exposes its workflow capabilities through several REST endpoints grouped under knowledge, tool, and trigger domains.

### Knowledge Workflow Endpoints

The knowledge API exposes a complete workflow lifecycle. From `ui/src/api/system-shared/knowledge.ts` we see operators such as `createWorkflowKnowledge`, `getWorkflowAction`, `workflowAction`, `getKnowledgeWorkflowFormList`, `getKnowledgeWorkflowDatasourceDetails`, `putKnowledgeWorkflow`, `getWorkflowActionPage`, `postTransformWorkflow`, `exportKnowledgeWorkflow`, and `importKnowledgeWorkflow` ([ui/src/api/system-shared/knowledge.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-shared/knowledge.ts)). These endpoints support creating workflow-driven knowledge bases, fetching action metadata, sourcing data through forms/datasources, exporting and importing entire workflows, and applying transformation workflows (`postTransformWorkflow`).

Server-side, the version endpoints are defined in `apps/knowledge/api/knowledge_version.py`. The mixin classes `KnowledgeVersionOperateAPI`, `KnowledgeVersionListAPI`, and `KnowledgeVersionPageAPI` declare the path parameters (`workspace_id`, `knowledge_id`, `knowledge_version_id`) and response serializers (`KnowledgeWorkflowVersionResult`, `KnowledgeListVersionResult`, `KnowledgePageVersionResult`) used to inspect, paginate, and operate on workflow versions ([apps/knowledge/api/knowledge_version.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/knowledge_version.py)).

The `exportKnowledgeBundle`/`importKnowledgeBundle` pair (declared in both `ui/src/api/system-shared/knowledge.ts` and `ui/src/api/knowledge/knowledge.ts`) packages a knowledge base — including its workflow definition and optionally its source files — into a portable ZIP bundle ([ui/src/api/knowledge/knowledge.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/knowledge/knowledge.ts)). This is the primary mechanism for sharing workflow-driven knowledge bases across environments.

### Tool Workflow Endpoints

Tools are first-class workflow citizens. From `ui/src/api/system-shared/tool.ts` we can see operators for importing a workflow into an existing tool (`importToolWorkflow`), listing tool workflow versions (`listToolWorkflowVersion`), updating a specific version (`updateToolWorkflowVersion`), publishing a tool (`publish`), and generating code from a tool workflow ([ui/src/api/system-shared/tool.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-shared/tool.ts)). The corresponding server-side definition in `apps/tools/api/tool.py` shows how the tool list endpoint accepts `scope` as `SHARED` or `WORKSPACE`, plus `folder_id`, `user_id`, and `name` filters, confirming that tools and their embedded workflows are scoped per workspace ([apps/tools/api/tool.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/tools/api/tool.py)).

### Triggers as Workflow Entry Points

Triggers provide the external entry point for executing application workflows. The `trigger.ts` API defines `pageTriggerTaskRecord` for paginating execution records of a given trigger and `getTriggerTaskRecordDetails` for fetching a single record's details ([ui/src/api/trigger/trigger.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/trigger/trigger.ts)). The companion resource-scoped helpers (`postResourceTrigger`, `putResourceTrigger`, `getResourceTriggerList`, `deleteResourceTrigger`) allow triggers to be attached to specific resources such as knowledge bases, making them integral to long-running automation.

## Architectural Relationships

```mermaid
flowchart LR
    A[Trigger] --> B[Application Engine]
    B --> C[Workflow Node: Knowledge]
    B --> D[Workflow Node: Tool]
    B --> E[Workflow Node: Condition / AI]
    C --> F[Versioned Knowledge Workflow]
    D --> G[Versioned Tool Workflow]
    F --> H[Export/Import Bundle]
    G --> H
    B -. streams .-> I[Chat Client<br/>chunk events]
```

The diagram captures how triggers initiate executions, the engine routes through typed workflow nodes, and each node type owns a versioned definition that can be packaged for transfer. Streaming chat output is reconstituted on the client from `Chunk` events carrying `runtime_node_id` and `child_node` references.

## Streaming and Node Output Model

The chat runtime reconstructs a workflow from incremental events. As shown in `ui/src/api/type/application.ts`, each chunk populates a node record with `buffer`, `reasoning_content_buffer`, `index`, `view_type`, and an `is_end` flag ([ui/src/api/type/application.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/application.ts)). `ChatManagement.chatMessageContainer` indexes these records by `chat_id`, and `appendChunk` merges new content into the most recent active node buffer, while `node_is_end` flags the closure of a node. The presence of `child_node` and `up_node_id` on every chunk indicates that the engine preserves the full directed-acyclic-graph structure of the workflow across stream events, enabling the UI to render nested branches faithfully.

## Permissions and Lifecycle

Workflow ownership and access are governed by the workspace/role model. The `role.ts` API exposes `getRoleMemberList`, `CreateMember`, and `deleteRoleMember` for managing who can operate a role-scoped resource ([ui/src/api/system/role.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system/role.ts)). Because knowledge bases and tools carry their own workflows, these membership endpoints indirectly gate who may edit, publish, or trigger a given workflow node.

## Common Failure Modes

- **Mismatched workflow versions**: When importing `importKnowledgeBundle` or calling `updateToolWorkflowVersion`, supplying data that references a non-existent `knowledge_version_id` or `tool_version_id` will fail; clients must first call `listKnowledgeVersion` / `listToolWorkflowVersion`.
- **Stale chunk buffers**: If the client-side `ChatManagement` registry loses a `chat_id` entry (e.g., on route change), incoming chunks are dropped because `chatMessageContainer` is keyed by `chat_id`.
- **Scope mismatch on tools**: Omitting `scope` (`SHARED` vs `WORKSPACE`) when calling `getToolListPage` returns an empty or wrong result set, since the parameter is required per `apps/tools/api/tool.py`.
- **Trigger ownership**: `postResourceTrigger` requires both `source_type` and `source_id`; using the wrong source type prevents the trigger from attaching to the intended workflow resource.

## See Also

- Knowledge Base Module
- Tool Integration
- Trigger and Automation
- Workspace and Role Permissions

---

<a id='page-3'></a>

## Knowledge Base, Tools, and Model Providers

### Related Pages

Related topics: [System Overview and Architecture](#page-1), [Application Engine and Workflow Nodes](#page-2), [Frontend, Deployment, and System Management](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/1Panel-dev/MaxKB/blob/main/README.md)
- [apps/knowledge/api/knowledge_version.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/knowledge_version.py)
- [apps/knowledge/api/termbase.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/termbase.py)
- [ui/src/api/knowledge/knowledge.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/knowledge/knowledge.ts)
- [ui/src/api/knowledge/document.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/knowledge/document.ts)
- [ui/src/api/knowledge/problem.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/knowledge/problem.ts)
- [ui/src/api/type/knowledge.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/knowledge.ts)
- [ui/src/api/type/model.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/model.ts)
- [ui/src/api/type/common.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/common.ts)
- [ui/src/api/system-resource-management/tool.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-resource-management/tool.ts)
- [ui/src/api/system-resource-management/paragraph.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-resource-management/paragraph.ts)
- [ui/src/api/system-shared/knowledge.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-shared/knowledge.ts)
- [ui/src/api/system-shared/document.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-shared/document.ts)
- [ui/src/api/system-shared/paragraph.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-shared/paragraph.ts)
- [ui/src/api/shared-workspace.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/shared-workspace.ts)
- [ui/src/api/system/role.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system/role.ts)
- [ui/src/api/trigger/trigger.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/trigger/trigger.ts)
- [ui/src/api/type/application.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/application.ts)
</details>

# Knowledge Base, Tools, and Model Providers

MaxKB is an open-source platform for building enterprise-grade agents. Its backend is built with Python/Django, the frontend uses Vue.js, and the LLM orchestration layer relies on LangChain. Knowledge is stored in PostgreSQL with the pgvector extension for vector search (`Source: [README.md]()`). This page describes three of the platform's foundational subsystems: the Knowledge Base, the Tools registry, and the Model Providers configuration, as exposed by the front-end API modules and the Django OpenAPI definitions.

## Knowledge Base Subsystem

The Knowledge Base is the highest-level container for retrievable content. A knowledge base owns a folder location, an optional embedding model reference, a description, and a collection of documents (`Source: [ui/src/api/type/knowledge.ts]()`):

```ts
interface knowledgeData {
  name: string
  folder_id?: string
  desc: string
  embedding_model_id?: string
  documents?: Array<any>
}
```

The CRUD surface for knowledge bases is implemented under the `/knowledge` prefix and includes paginated listing, detail retrieval, update, deletion, and a dedicated re-embedding endpoint that re-vectorizes all content with the configured embedding model (`Source: [ui/src/api/knowledge/knowledge.ts]()`).

### Documents, Paragraphs, Problems, and Termbase

Inside each knowledge base, documents are the primary ingestion units. Document operations include create, list, detail, update, delete, batch operations (multi-sync, multi-migrate, batch generate related, batch edit hit handling, batch refresh, batch tokenize), and specialized document sources such as QA, table, split-pattern, web, and Lark (Feishu) (`Source: [ui/src/api/knowledge/document.ts](), [ui/src/api/system-resource-management/document.ts](), [ui/src/api/system-shared/document.ts]()`).

Documents are split into Paragraphs, each carrying a title, content, an `is_active` flag, and an associated list of Problems used for Q&A matching:

```ts
// paragraph create payload
{
  "content": "string",
  "title": "string",
  "is_active": true,
  "problem_list": [{ "content": "string" }]
}
```

(`Source: [ui/src/api/system-resource-management/paragraph.ts](), [ui/src/api/system-shared/paragraph.ts]()`)

Problems are managed independently as well, with endpoints for paginated listing, detail (which returns the related paragraphs), update, and batch association of paragraphs (`Source: [ui/src/api/knowledge/problem.ts]()`).

The Termbase sub-resource models the problem/question catalog for a knowledge base. Its API exposes paginated query and deletion scoped to `(workspace_id, knowledge_id, problem_id)`, which enforces workspace-level isolation (`Source: [apps/knowledge/api/termbase.py]()`).

### Versions and Workflows

Knowledge bases also support versioning via the `KnowledgeVersion*API` classes. Endpoints cover single-version operations, list, and paged query, all keyed by `knowledge_version_id` and an optional `name` filter, and returning the `KnowledgeWorkflowVersionResult`, `KnowledgeListVersionResult`, and `KnowledgePageVersionResult` serializers respectively (`Source: [apps/knowledge/api/knowledge_version.py]()`). This enables rollback and side-by-side comparison of workflow versions.

## Tools Subsystem

Tools are external capabilities that an agent can invoke. They are registered under `/system/resource/tool` and expose CRUD plus a `test_connection` endpoint that validates credentials before saving (`Source: [ui/src/api/system-resource-management/tool.ts]()`):

| Operation | Endpoint | Purpose |
|-----------|----------|---------|
| Page list | `GET /system/resource/tool/{page}/{size}` | Paginated tool inventory |
| Detail | `GET /system/resource/tool/{tool_id}` | Retrieve one tool |
| Update | `PUT /system/resource/tool/{tool_id}` | Modify tool configuration |
| Test | `POST /system/resource/tool/test_connection` | Validate before save |
| Delete | `DELETE /system/resource/tool/{tool_id}` | Remove a tool |

The shared API surface also exposes the same set across workspace boundaries (`Source: [ui/src/api/system-shared/document.ts]() shared re-exports`), and MCP (Model Context Protocol) tools are listed via `getMcpTools` for use inside workflows (`Source: [ui/src/api/system-shared/knowledge.ts]()`). Triggers, which fire workflows on external events, are created via `postResourceTrigger(source_type, source_id, data)` and their execution records queried with `pageTriggerTaskRecord` (`Source: [ui/src/api/trigger/trigger.ts]()`).

## Model Providers

Model Providers define the upstream LLMs and embedding models that power both retrieval and generation. The TypeScript type definitions describe `Provider`, `Model`, `BaseModel`, `CreateModelRequest`, and `EditModelRequest`, with `BaseModel` carrying `name`, `desc`, and `model_type` (`Source: [ui/src/api/type/model.ts]()`). The `embedding_model_id` on a knowledge base binds a specific base model to retrieval, while chat applications reference additional long-term memory parameters (`long_term_model_id`, `long_term_model_params_setting`, `long_term_trigger_setting`, `long_term_trigger_type`) on the application object (`Source: [ui/src/api/type/application.ts]()`).

### Workspace Sharing and Roles

Cross-workspace sharing of knowledge bases is coordinated through `shared-workspace` endpoints, including `getProblemsPage`, `getUserGroupList`, and `getUserGroupUserList` which scope resources by `workspace_id` and `knowledge_id` (`Source: [ui/src/api/shared-workspace.ts]()`). Role-based access (`getRoleList`, `CreateMember`, `deleteRoleMember`) governs who may consume or administer these resources (`Source: [ui/src/api/system/role]()`).

## End-to-End Data Flow

```mermaid
flowchart LR
  User[User / Frontend Vue] --> KB[Knowledge Base API]
  KB --> Doc[Documents]
  Doc --> Para[Paragraphs]
  Para --> Prob[Problems / Termbase]
  KB --> Emb[Embedding Model]
  Emb --> PG[(PostgreSQL + pgvector)]
  Tools[Tools / MCP] --> Agent
  Models[Model Providers] --> Agent
  Trigger[Triggers] --> Workflow
  Workflow --> KB
```

## Common Failure Modes

- **Re-embedding required after model swap:** changing `embedding_model_id` only updates the record; existing vectors remain stale until `putReEmbeddingKnowledge` runs (`Source: [ui/src/api/knowledge/knowledge.ts]()`).
- **Workspace isolation:** Termbase and shared endpoints require both `workspace_id` and `knowledge_id`; omitting either returns a validation error (`Source: [apps/knowledge/api/termbase.py]()`).
- **Tool credentials:** tools saved without passing `test_connection` may fail at invocation time; always validate before persisting (`Source: [ui/src/api/system-resource-management/tool.ts]()`).
- **Version mismatch:** `KnowledgeVersionOperateAPI` requires `knowledge_version_id` in the path; callers must list versions before operating on one (`Source: [apps/knowledge/api/knowledge_version.py]()`).

## See Also

- Application and Workflow configuration (`ui/src/api/type/application.ts`)
- Triggers and scheduling (`ui/src/api/trigger/trigger.ts`)
- Role and permission management (`ui/src/api/system/role.ts`)

---

<a id='page-4'></a>

## Frontend, Deployment, and System Management

### Related Pages

Related topics: [System Overview and Architecture](#page-1), [Application Engine and Workflow Nodes](#page-2), [Knowledge Base, Tools, and Model Providers](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/1Panel-dev/MaxKB/blob/main/README.md)
- [ui/src/api/knowledge/problem.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/knowledge/problem.ts)
- [ui/src/api/knowledge/termbase.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/knowledge/termbase.ts)
- [ui/src/api/system-shared/knowledge.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-shared/knowledge.ts)
- [ui/src/api/system-shared/document.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-shared/document.ts)
- [ui/src/api/system-shared/paragraph.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-shared/paragraph.ts)
- [ui/src/api/system-shared/tool.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-shared/tool.ts)
- [ui/src/api/system-resource-management/document.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-resource-management/document.ts)
- [ui/src/api/system-resource-management/paragraph.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-resource-management/paragraph.ts)
- [ui/src/api/system-resource-management/tool.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-resource-management/tool.ts)
- [ui/src/api/system/role.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system/role.ts)
- [ui/src/api/trigger/trigger.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/trigger/trigger.ts)
- [ui/src/api/shared-workspace.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/shared-workspace.ts)
- [ui/src/api/type/common.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/common.ts)
- [ui/src/api/type/knowledge.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/knowledge.ts)
- [ui/src/api/type/application.ts](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/application.ts)
- [apps/knowledge/api/knowledge_version.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/knowledge_version.py)
- [apps/knowledge/api/termbase.py](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/termbase.py)
</details>

# Frontend, Deployment, and System Management

## Overview

MaxKB is an open-source platform for building enterprise-grade agents. The system is built on a clear separation of concerns: a Vue.js frontend communicates with a Python/Django backend, an LLM framework (LangChain) handles model orchestration, and PostgreSQL with the pgvector extension stores both relational data and vector embeddings. Source: [README.md](https://github.com/1Panel-dev/MaxKB/blob/main/README.md).

This page covers the **frontend API layer** that drives the management console, the **system management capabilities** exposed to administrators (roles, resources, shared workspaces), and the **knowledge base subsystems** (documents, paragraphs, problems, termbase) that operators interact with daily. Deployment details (tech stack, runtime, licensing) are summarized from the project README.

## Frontend API Architecture

The frontend is implemented in Vue.js and consumes the backend through a thin, strongly-typed API client layer located under `ui/src/api/`. The layer is organized by domain:

- **Per-domain APIs** (e.g., `ui/src/api/knowledge/problem.ts`, `ui/src/api/knowledge/termbase.ts`) expose operations scoped to a single knowledge base, using a dynamic `prefix.value` resolved at runtime.
- **System resource management** APIs (e.g., `ui/src/api/system-resource-management/document.ts`, `ui/src/api/system-resource-management/paragraph.ts`, `ui/src/api/system-resource-management/tool.ts`) target the global `/system/resource/...` endpoint namespace and are used for administrative views.
- **Shared resource APIs** (e.g., `ui/src/api/system-shared/knowledge.ts`, `ui/src/api/system-shared/document.ts`, `ui/src/api/system-shared/tool.ts`) target the `/system/shared/...` namespace and are used when an administrator exposes a resource across workspaces.

Every API module returns a `Result<T>` wrapper, as declared in [`ui/src/api/knowledge/problem.ts`](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/knowledge/problem.ts) and other modules, and accepts an optional `Ref<boolean>` `loading` flag to integrate with the global loading indicator.

### Common Type Contracts

The shared `pageRequest` and `PageList<T>` interfaces in [`ui/src/api/type/common.ts`](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/common.ts) are reused by every paginated endpoint. The `knowledgeData` interface in [`ui/src/api/type/knowledge.ts`](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/knowledge.ts) standardizes the create/update payload for knowledge bases (`name`, `folder_id`, `desc`, `embedding_model_id`, `documents`). Application-level streaming types such as `chatType` and `Chunk` live in [`ui/src/api/type/application.ts`](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/application.ts) and are used by the chat UI to render token-by-token responses.

```ts
interface pageRequest {
  current_page: number
  page_size: number
}

interface PageList<T> {
  current: number
  size: number
  total: number
  records: T
}
```
Source: [`ui/src/api/type/common.ts`](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/type/common.ts).

## Knowledge Base Management

The knowledge base subsystem provides CRUD operations for documents, paragraphs, problems, and termbase entries. The frontend API surface is mirrored between the per-knowledge module and the system-shared module so that both owners and administrators can manage the same data through different URL prefixes.

### Documents and Paragraphs

Document-level operations are exposed in [`ui/src/api/system-resource-management/document.ts`](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-resource-management/document.ts), which exports batch handlers such as `putBatchGenerateRelated`, `putBatchEditHitHandling`, `putBatchRefresh`, `putBatchTokenize`, `putMulSyncDocument`, and migration helpers (`putMigrateMulDocument`). Lark/Feishu integration is also present (`getLarkDocumentList`, `putLarkDocumentSync`, `putMulLarkSyncDocument`, `importLarkDocument`).

Paragraph-level operations in [`ui/src/api/system-resource-management/paragraph.ts`](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-resource-management/paragraph.ts) use the URL pattern `/system/resource/knowledge/{knowledge_id}/document/{document_id}/paragraph` and accept a payload of `{ content, title, is_active, problem_list: [{ content }] }`. A `getParagraphPage` function uses the standard `pageRequest` shape for paged listing. The shared workspace variant at [`ui/src/api/system-shared/paragraph.ts`](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-shared/paragraph.ts) follows the same pattern under `/system/shared/knowledge`.

### Problems and Termbase

`ui/src/api/knowledge/problem.ts` exposes the problem lifecycle: paginated listing, update (`putProblems`), delete (`delProblems`), detail-with-paragraphs (`getDetailProblems`), and batch association (`putMulAssociationProblem` accepts `problem_id_list` and `paragraph_list`).

`ui/src/api/knowledge/termbase.ts` mirrors this shape for termbase entries, including a `putMulTermbase` (batch delete) and `exportMulTermbase` (batch export) endpoint.

The backend counterpart is documented in [`apps/knowledge/api/termbase.py`](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/termbase.py), which declares OpenAPI parameters for `workspace_id`, `knowledge_id`, `problem_id`, `current_page`, and `page_size`, and a `TermbaseDeleteAPI` mixin.

### Knowledge Versions

Knowledge bases can be published as versioned workflows. The `KnowledgeVersionOperateAPI`, `KnowledgeVersionListAPI`, and `KnowledgeVersionPageAPI` classes in [`apps/knowledge/api/knowledge_version.py`](https://github.com/1Panel-dev/MaxKB/blob/main/apps/knowledge/api/knowledge_version.py) declare the `knowledge_version_id` path parameter and reuse `KnowledgeVersionAPI` parameters (`workspace_id`, `knowledge_id`). The response models `KnowledgeWorkflowVersionResult`, `KnowledgeListVersionResult`, and `KnowledgePageVersionResult` are defined elsewhere in the same module.

## System Management

Administrators manage platform-wide resources through the `/system/...` API surface. The role subsystem in [`ui/src/api/system/role.ts`](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system/role.ts) exposes role listing, role templates, role creation/update, permission binding (`saveRolePermission`), and member management (`CreateMember`, `deleteRoleMember` using the `add_member` / `remove_member/{user_relation_id}` routes).

The tool subsystem in [`ui/src/api/system-resource-management/tool.ts`](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-resource-management/tool.ts) and [`ui/src/api/system-shared/tool.ts`](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/system-shared/tool.ts) covers tool registration (`postTool`, `putTool`), icon upload (`putToolIcon`), connection testing (`postToolTestConnection`), debug invocations, paging (`getToolListPage`), store/internal tools (`addInternalTool`, `addStoreTool`, `updateStoreTool`), record retrieval, skill file upload/download (`uploadSkillFile`, `downloadSkillFile`), and code generation.

The trigger subsystem in [`ui/src/api/trigger/trigger.ts`](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/trigger/trigger.ts) provides paginated trigger listing (`pageTrigger`, `getTriggerList`), CRUD (`postTrigger`, `putTrigger`, `deleteTrigger`, `delMulTrigger`), activation (`activateMulTrigger`), execution history (`pageTriggerTaskRecord`, `getTriggerTaskRecordDetails`), and a resource-scoped variant (`postResourceTrigger`, `putResourceTrigger`, `getResourceTriggerList`, `getResourceTriggerDetail`, `deleteResourceTrigger`) that targets `/{source_type}/{source_id}/trigger`.

The shared workspace API in [`ui/src/api/shared-workspace.ts`](https://github.com/1Panel-dev/MaxKB/blob/main/ui/src/api/shared-workspace.ts) is the bridge between the system-shared and per-workspace data scopes. It exposes `getProblemsPage` (paginated problem listing scoped to a workspace), `getUserGroupUserList` and `getUserGroupList` (for the `KNOWLEDGE` resource type), and paragraph listing helpers.

```mermaid
flowchart LR
  UI[Vue.js Frontend] -->|ui/src/api/*| FE[Frontend API Layer]
  FE -->|/system/resource/*| ADM[System Resource APIs]
  FE -->|/system/shared/*| SHR[System Shared APIs]
  FE -->|/knowledge/*| KB[Per-Knowledge APIs]
  FE -->|/trigger/*| TRG[Trigger APIs]
  ADM --> DJ[Django Backend]
  SHR --> DJ
  KB --> DJ
  TRG --> DJ
  DJ --> PG[(PostgreSQL + pgvector)]
  DJ --> LC[LangChain LLM Framework]
```

## Deployment and Runtime

The technical stack defined in the project README is the contract every other system must respect: **Vue.js** for the frontend, **Python / Django** for the backend, **LangChain** for LLM orchestration, and **PostgreSQL with pgvector** for persistence and vector search. Source: [README.md](https://github.com/1Panel-dev/MaxKB/blob/main/README.md). The repository is distributed under the **GNU General Public License version 3 (GPLv3)**. Source: [README.md](https://github.com/1Panel-dev/MaxKB/blob/main/README.md).

When bringing up a new instance, operators should ensure:

1. PostgreSQL is reachable and the pgvector extension is enabled for vector columns used by the knowledge base.
2. The Django backend is configured to expose the URL namespaces consumed by the frontend (`/system/resource/...`, `/system/shared/...`, `/knowledge/...`, `/trigger/...`), as evidenced by the prefixes in the API modules cited above.
3. The LLM credentials required by LangChain are provided via the application configuration, so that embeddings and chat completions can be issued by the backend.

## See Also

- [Knowledge Base Subsystem](README.md)
- [Application and Chat Types](ui/src/api/type/application.ts)
- [Shared Workspace API](ui/src/api/shared-workspace.ts)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: 1Panel-dev/MaxKB

Summary: Found 8 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: runtime_trace
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Repro command: `docker run -d --name=maxkb --restart=always -p 8080:8080 -v ~/.maxkb:/opt/maxkb 1panel/maxkb`
- Evidence: identity.distribution | https://github.com/1Panel-dev/MaxKB

## 2. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/1Panel-dev/MaxKB

## 3. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/1Panel-dev/MaxKB

## 4. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/1Panel-dev/MaxKB

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/1Panel-dev/MaxKB

## 6. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/1Panel-dev/MaxKB

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/1Panel-dev/MaxKB

## 8. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/1Panel-dev/MaxKB

<!-- canonical_name: 1Panel-dev/MaxKB; human_manual_source: deepwiki_human_wiki -->