This document describes the application server architecture and web interface components of DB-GPT. It covers the FastAPI-based REST API layer, the Next.js/React web frontend, and how these components integrate to provide user-facing functionality. For information about the underlying service implementations, see Application Layer and Services. For deployment configurations, see Docker Compose Deployment.
DB-GPT's application layer consists of two primary components:
These components run together on port 5670 by default, providing a unified interface for interacting with DB-GPT's core capabilities including RAG, GBI, multi-agent systems, and AWEL workflows.
The DB-GPT web server is built on FastAPI, providing high-performance asynchronous API endpoints. The application entry point initializes the server on port 5670 (configurable via DBGPT_PORT environment variable) and registers modular router components for different functional areas.
Web Server Architecture
Sources: README.md:145-159, System Architecture Diagrams, .gitignore:160-184
The web server initializes with configuration loaded from .env files (filtered by .gitignore patterns .env*) and TOML configuration files for model parameters. The startup sequence orchestrates database connections, service instantiation, and router registration.
Server Startup Sequence
Sources: README.md:146-148, .gitignore:9-14, .gitignore:160-184
The REST API follows RESTful conventions and is organized by functional domain under the versioned prefix /api/v1/. Each router module in packages/dbgpt-serve exposes endpoints for its respective domain.
| API Category | Base Path | Primary Functions | Package Location |
|---|---|---|---|
| Knowledge | /api/v1/knowledge | Document upload, space management, synchronization | packages/dbgpt-serve |
| Chat | /api/v1/chat | Conversation management, message streaming | packages/dbgpt-serve |
| Agent | /api/v1/agent | Agent configuration, task execution | packages/dbgpt-app |
| Model | /api/v1/model | Model listing, worker management, metadata | packages/dbgpt-core |
| AWEL | /api/v1/awel | Workflow management, DAG execution | packages/dbgpt-core |
| Database | /api/v1/database | Database connection, query execution (GBI) | packages/dbgpt-ext |
Sources: README.md:122-129, System Architecture Diagrams, README.md:150-153
The following diagram illustrates how HTTP requests flow through the application server to backend services:
Sources: System Architecture Diagrams
The API supports multiple response formats:
Sources: System Architecture Diagrams
The web interface is built with Next.js and React, located in the /web/ directory. The application is compiled to /web/build for production serving, with development assets in /web/.next/. The frontend communicates with the backend exclusively through REST API endpoints.
Next.js Application Structure
Sources: README.md:130-139, .gitignore:160-184, README.md:113
The web interface integrates with the backend through a well-defined API contract. Key integration points include:
Sources: System Architecture Diagrams
The web interface provides several key functional areas visible in the application screenshots:
| Feature Area | Description | Key Components | Screenshot Reference |
|---|---|---|---|
| Chat Interface | Interactive chat with AI models, data agents | Message history, input box, streaming display | app_chat_v0.6 |
| Knowledge Management | Document upload and space management | File uploader, space selector, sync status | app_manage_chat_data_v0.6 |
| Agent Workspace | Multi-agent configuration and AWEL flows | Workflow editor, agent selector, execution logs | agent_prompt_awel_v0.6 |
| Dashboard | Analytics and visualization with GPT-Vis protocol | Charts, metrics, data reports | chat_dashboard_display_v0.6 |
| Model Management | Model selection and SMMF configuration | Model list, parameter editor, worker status | Model settings UI |
Sources: README.md:130-139, README.md:113
The web server connects to a metadata database (MySQL/SQLite) for persistent storage of application metadata, user data, and system state. The database implementation uses SQLAlchemy for ORM and connection management.
Database Storage Architecture
Sources: packages/dbgpt-core/src/dbgpt/storage/metadata/db_storage.py:1-134, docs/docs/upgrade/v0.5.1.md:1-31
The SQLAlchemyStorage class packages/dbgpt-core/src/dbgpt/storage/metadata/db_storage.py31-134 implements the StorageInterface with methods for save, update, save_or_update, load, delete, and query operations. The DatabaseManager.build_from() method packages/dbgpt-core/src/dbgpt/storage/metadata/db_storage.py46-48 accepts either a database URL string or an existing DatabaseManager instance for flexible configuration.
Database Schema Management
The database schema is version-controlled with migration support. For example, the v0.5.1 upgrade adds an error_message column to the dbgpt_serve_flow table docs/docs/upgrade/v0.5.1.md26-30 for tracking AWEL workflow execution errors.
DB-GPT provides a command-line interface through the dbgpt command that can both control the server and interact with running services. The CLI uses the packages/dbgpt-client package for API communication.
CLI Command Architecture
Sources: README.md:145-159, README.md:122-129
The web server is containerized for deployment with multi-stage Docker builds. The configuration builds both the FastAPI backend and Next.js frontend, serving them through a unified container process.
Docker Container Architecture
Sources: README.md:146-148, .gitignore:160-184, .gitignore:27-29
The web server container exposes port 5670 for HTTP and WebSocket connections. Docker volumes persist data across container restarts:
dbgpt-data - Application data and databasesdbgpt-logs - Server and application logs (excluded from git by .gitignore)models - Optional volume for local model weights (soft link support)Environment variables from .env files configure database connections, model endpoints, and other runtime parameters.
The web server's behavior is controlled through environment variables and configuration files. Configuration sources are loaded in a specific order with later sources overriding earlier ones.
| Configuration Source | Purpose | Example Parameters | Location |
|---|---|---|---|
.env file | Environment-specific settings | DBGPT_HOST, DBGPT_PORT, LLM_MODEL | Root directory (gitignored) |
.toml files | Model and proxy configurations | dbgpt-proxy-*.toml, dbgpt-local-*.toml | configs/ directory |
| Database settings | Connection strings and pool size | DB_HOST=localhost, DB_PORT=3306 | .env file |
| Volume mounts | Data persistence paths | /app/data, /app/logs | Docker Compose |
.plugin_env | Plugin-specific settings | Plugin activation flags | Root directory (gitignored) |
Sources: README.md:146-148, .gitignore:9-14, .gitignore:152
Configuration File Patterns
The .gitignore file excludes several configuration patterns from version control:
.env* - All environment variable files for different environments.plugin_env - Plugin configurationconfigs/my - Custom configuration directory for local overridesThe web server implements several security measures:
These security features are configured through environment variables and can be customized for different deployment scenarios.
Sources: System Architecture Diagrams
The FastAPI-based architecture provides several performance benefits:
For production deployments, the web server can be horizontally scaled behind a load balancer, with shared database and storage backends ensuring state consistency across instances.
Sources: System Architecture Diagrams, README.md:140-159
Refresh this wiki