System Architecture

Relevant source files

• README.ja.md
• README.md
• README.zh.md
• assets/LOGO_SMALL.png
• assets/Twitter_LOGO.png
• assets/Youtube_LOGO.png
• assets/ding.jpg
• assets/wechat.jpg
• docs/docs/upgrade/v0.5.1.md
• packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml
• packages/dbgpt-accelerator/dbgpt-acc-auto/src/dbgpt_acc_auto/_version.py
• packages/dbgpt-accelerator/dbgpt-acc-flash-attn/pyproject.toml
• packages/dbgpt-accelerator/dbgpt-acc-flash-attn/src/dbgpt_acc_flash_attn/_version.py
• packages/dbgpt-app/pyproject.toml
• packages/dbgpt-app/src/dbgpt_app/_version.py
• packages/dbgpt-client/pyproject.toml
• packages/dbgpt-client/src/dbgpt_client/_version.py
• packages/dbgpt-core/pyproject.toml
• packages/dbgpt-core/src/dbgpt/_version.py
• packages/dbgpt-core/src/dbgpt/storage/metadata/db_storage.py
• packages/dbgpt-ext/pyproject.toml
• packages/dbgpt-ext/src/dbgpt_ext/_version.py
• packages/dbgpt-serve/pyproject.toml
• packages/dbgpt-serve/src/dbgpt_serve/_version.py
• pyproject.toml
• uv.lock

Purpose and Scope

This document describes the high-level system architecture of DB-GPT, explaining how the framework's components are organized and how they interact. DB-GPT follows a modular, layered architecture implemented as a monorepo with seven packages.

For detailed information about specific subsystems, see:

• Core framework abstractions and AWEL workflow engine: Core Framework and AWEL
• Package structure and dependency management: Package Structure and Dependencies
• Model inference and management: Service-oriented Multi-model Management Framework (SMMF)
• Data persistence and storage backends: Storage Architecture and Databases
• API server and web application: Application Server and Web Interface

---

Architectural Overview

DB-GPT implements a four-layer architecture that separates concerns and enables modular development:

Layered Architecture

Sources: README.md62-81 pyproject.toml31-40

Design Philosophy

The architecture follows these principles:

Principle	Implementation
Modularity	Seven independent packages with clear boundaries
Layering	Strict dependency hierarchy (no circular dependencies)
Extensibility	Plugin-based storage, model adapters, and operators
Optional Features	Feature-specific dependencies through extras
Type Safety	Pydantic models and type hints throughout

The monorepo structure enables:

• Unified versioning across all packages (currently v0.7.5)
• Shared dependency management via uv package manager
• Selective installation based on use case
• Coordinated releases and testing

Sources: packages/dbgpt-core/pyproject.toml1-26 packages/dbgpt-app/pyproject.toml1-21

---

Monorepo Package Structure

DB-GPT's codebase is organized as a monorepo with seven packages, each serving a distinct purpose:

Package Dependency Graph

Sources: pyproject.toml31-40 packages/dbgpt-ext/pyproject.toml12-15 packages/dbgpt-serve/pyproject.toml12-14 packages/dbgpt-client/pyproject.toml12-22 packages/dbgpt-app/pyproject.toml12-20

Package Responsibilities

1. dbgpt-core (dbgpt package)

The foundation package providing core abstractions and interfaces.

Key Components:

• dbgpt.core.awel - AWEL workflow engine (DAG execution, operators, triggers)
• dbgpt.core.interface.storage - Storage interfaces (StorageInterface, QuerySpec, ResourceIdentifier)
• dbgpt.agent - Multi-agent framework (agent profiles, memory, tools)
• dbgpt.rag - RAG framework (knowledge management, retrieval strategies)
• dbgpt.datasource - Data source abstraction layer
• dbgpt.model - Model management interfaces

Optional Dependencies (selected via extras):

Sources: packages/dbgpt-core/pyproject.toml1-205 packages/dbgpt-core/src/dbgpt/_version.py1

2. dbgpt-ext

Concrete implementations of storage backends and data sources.

Key Components:

• dbgpt_ext.storage.vector_store - Vector database implementations (Milvus, Chroma, Elasticsearch, PGVector, Weaviate, OceanBase)
• dbgpt_ext.storage.knowledge_graph - Graph database implementations (TuGraph, Neo4j)
• dbgpt_ext.datasource - Database connectors (MySQL, PostgreSQL, Oracle, ClickHouse, Hive, DuckDB, MSSQL)
• dbgpt_ext.rag - Document parsers and chunking strategies

Optional Dependencies:

Sources: packages/dbgpt-ext/pyproject.toml1-106 packages/dbgpt-ext/src/dbgpt_ext/_version.py1

3. dbgpt-serve

Service-layer implementations providing business logic.

Key Services:

• RAG service - Document management and retrieval pipeline
• Evaluation service - Benchmarking and performance metrics
• Storage manager - Factory for storage connector creation

Dependencies: dbgpt-ext (provides storage implementations)

Sources: packages/dbgpt-serve/pyproject.toml1-44 packages/dbgpt-serve/src/dbgpt_serve/_version.py1

4. dbgpt-client

Python SDK for interacting with DB-GPT services.

Key Components:

• Client APIs for service invocation
• Request/response schemas
• Connection management

Dependencies: dbgpt[client,cli], dbgpt_ext, SQLAlchemy, cloudpickle

Sources: packages/dbgpt-client/pyproject.toml1-47 packages/dbgpt-client/src/dbgpt_client/_version.py1

5. dbgpt-app

Top-level application orchestration and integration.

Key Components:

• Application initialization and configuration
• Knowledge service integration
• Workflow orchestration

Dependencies: All other packages (dbgpt-acc-auto, dbgpt, dbgpt-ext, dbgpt-serve, dbgpt-client)

Optional Dependencies:

Sources: packages/dbgpt-app/pyproject.toml1-65 packages/dbgpt-app/src/dbgpt_app/_version.py1

6. dbgpt-accelerator

Hardware acceleration for model inference.

Sub-packages:

• dbgpt-acc-auto - Automatic acceleration selection based on hardware
• dbgpt-acc-flash-attn - Flash Attention integration

Hardware Support:

Sources: packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml1-150 packages/dbgpt-accelerator/dbgpt-acc-flash-attn/pyproject.toml1-33

7. dbgpt-sandbox

Isolated code execution environment for agent tasks.

Sources: pyproject.toml38

---

Component Interaction Patterns

Storage Architecture Integration

The storage layer demonstrates DB-GPT's abstraction pattern:

Key Classes:

Class	Location	Purpose
StorageInterface[T, D]	dbgpt.core.interface.storage	Generic storage interface with type parameters for domain object (T) and data model (D)
StorageItemAdapter[T, D]	dbgpt.core.interface.storage	Converts between domain objects and storage models
QuerySpec	dbgpt.core.interface.storage	Database-agnostic query specification
SQLAlchemyStorage	dbgpt_ext.storage.metadata.db_storage	SQLAlchemy-based implementation
DatabaseManager	dbgpt_ext.storage.metadata.db_manager	Session and connection management

Sources: packages/dbgpt-core/src/dbgpt/storage/metadata/db_storage.py1-136

Dependency Injection and Configuration

Configuration is managed through:

• tomli (reading TOML files) and tomlkit (writing TOML files)
• Pydantic models for validation (pydantic>=2.6.0)
• Environment variable override support
• CLI argument parsing via click

Sources: packages/dbgpt-core/pyproject.toml14-25

---

Extension Mechanisms

DB-GPT provides multiple extension points for customization:

1. Optional Dependencies Strategy

The framework uses Python extras to provide optional features without bloating the base installation:

Conflict Resolution:

The monorepo uses uv conflict specifications to prevent incompatible extras:

Sources: packages/dbgpt-core/pyproject.toml176-193 packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml110-118

2. Storage Backend Plugin Pattern

Vector stores, knowledge graphs, and data sources are implemented as plugins in dbgpt-ext:

Storage Type	Implementations	Installation Extra
Vector Store	Milvus, Chroma, Elasticsearch, PGVector, Weaviate, OceanBase	storage_milvus, storage_chromadb, etc.
Knowledge Graph	TuGraph, Neo4j	graph_rag
Data Source	MySQL, PostgreSQL, Oracle, ClickHouse, Hive, DuckDB, MSSQL	datasource_mysql, datasource_postgres, etc.

Sources: packages/dbgpt-ext/pyproject.toml27-89

3. Model Adapter Pattern

Model integrations support both local and proxy (API) deployments:

Local Models:

• llama_cpp - LLAMA.cpp for CPU/Metal inference
• hf - HuggingFace Transformers
• vllm - High-throughput inference (Linux only)
• mlx - Apple Silicon optimized (macOS only)

Proxy Models:

• proxy_openai - OpenAI API compatible
• proxy_ollama - Ollama local server
• proxy_zhipuai - Zhipu AI (ChatGLM)
• proxy_tongyi - Alibaba Tongyi
• proxy_qianfan - Baidu Qianfan
• proxy_anthropic - Anthropic Claude

Sources: packages/dbgpt-core/pyproject.toml116-143

---

Build and Dependency Management

UV Package Manager

DB-GPT uses uv as its package manager for fast, reliable dependency resolution:

Key Features:

• Fast resolution - Significantly faster than pip
• Reproducible builds - Lock file ensures consistency (uv.lock)
• Workspace support - Manages all seven packages in monorepo
• Conflict detection - Prevents incompatible extra combinations

Sources: pyproject.toml42-61 uv.lock1-4

Build System

All packages use hatchling as the build backend:

This provides:

• PEP 517/518 compliant builds
• Test and example exclusion from distribution
• Consistent package structure across all modules

Sources: packages/dbgpt-core/pyproject.toml167-203 packages/dbgpt-ext/pyproject.toml96-105

Version Synchronization

All packages maintain synchronized versioning:

Sources: packages/dbgpt-core/src/dbgpt/_version.py1 packages/dbgpt-ext/src/dbgpt_ext/_version.py1 packages/dbgpt-app/src/dbgpt_app/_version.py1 packages/dbgpt-serve/src/dbgpt_serve/_version.py1 packages/dbgpt-client/src/dbgpt_client/_version.py1

---

Summary

DB-GPT's architecture achieves modularity through:

1. Four-Layer Design - Clear separation between UI, application, framework, and external systems
2. Seven Packages - Independent, focused modules with explicit dependencies
3. Optional Features - Pay-for-what-you-use approach via extras
4. Type Safety - Pydantic models and generic interfaces throughout
5. Extensibility - Plugin patterns for storage, models, and data sources

The monorepo structure with uv provides efficient development while maintaining clear boundaries. Each package can be installed independently based on deployment requirements, from lightweight clients to full-featured servers.

For implementation details of specific subsystems, refer to:

• Core Framework and AWEL - AWEL workflow engine and core abstractions
• Package Structure and Dependencies - Detailed dependency analysis
• SMMF - Model inference and management
• Storage Architecture - Database and persistence layer
• Application Server - API and web interface

Sources: README.md1-363 pyproject.toml1-86 all package pyproject.toml files