# tsinghuadatabasegroup/db-gpt architecture

> Architecture diagram of the GitHub repository tsinghuadatabasegroup/db-gpt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tsinghuadatabasegroup/db-gpt
- Repository: https://github.com/tsinghuadatabasegroup/db-gpt

## Overview

##### Project Type and Purpose
- This is a full-stack “Database GPT” application:
- A Python/FastAPI backend that orchestrates LLM-based diagnostics, knowledge-base Q&A, anomaly simulation, and metrics ingestion.
- A Vue3/Vite web UI (in `webui/`) plus Streamlit pages (`webui_pages/`) for user interaction.
- A multi-agent framework (`multiagents/`) that dispatches tasks to various LLMs, tools, and knowledge sources.
- Monitoring and anomaly-triggering micro-services (Prometheus, Alertmanager, PostgreSQL) run in Docker (`prometheus_service_docker/`).

##### File-Structure Analysis
- Top-level directories:
- `server/`: FastAPI endpoints, database models/repos (`server/db/`), LLM & chat handlers, knowledge-base APIs, memory modules, model-worker adapters, web UI assets (`server/static/`).
- `multiagents/`: Core orchestration library—agents, environments, tools (index advisor, query advisor, metric monitor), LLM adapters, memory, reasoning algorithms.
- `anomaly_trigger/`: Scripts to simulate and inject database anomalies.
- `doc2knowledge/`, `document_loaders/`, `knowledge_base/`: Document ingestion, chunking, embedding, vector store support.
- `prometheus_service_docker/`: Docker Compose definitions for Prometheus+Alertmanager+Postgres+Python webhook.
- `webui/`: Vue3 front-end application code.
- `webui_pages/`: Streamlit/Vue stand-alone pages for diagnosis/dialogue/report.
- Configs and data: under `configs/`, `diagnostic_files/`, `test_cases/`, `logs/`.
- Tests: routings, API, tools, document loaders, vector DB backends.

##### Key Architectural Insights from README
- The system uses a RAG pattern: combine vector DB (Chroma/FAISS/ES) with expert prompts.
- Multi-path extraction, tool-APIs for index optimization, query rewrite, hints.
- Supports both cloud (OpenAI) and local LLMs (vLLM, quantized models).
- Prometheus pulls metrics, Alertmanager triggers alerts, a Python webhook records them for diagnosis.

1. User Interface
- Vue3 Web UI (SPA)
- Streamlit Apps (diagnosis, dialogues, reports)
2. API Backend (FastAPI + Uvicorn)
- REST/gRPC endpoints (`server/api.py`, `server/embeddings_api.py`, `server/llm_api.py`)
- DB Layer (PostgreSQL via SQLAlchemy in `server/db/`)
- Knowledge-base service (ChromaDB/FAISS/ES adapters in `server/knowledge_base/`)
- Multiagent Orchestrator (`multiagents/`, via `multiagents/initialization.py`)
- Model-workers (local/in-cloud LLM adapters)
- Memory & feedback storage (vector DB + relational DB)
3. Knowledge Storage
- Vector store (Chroma, FAISS, Milvus, Elasticsearch)
- Relational DB (PostgreSQL) for chat history, metadata, feedback
4. LLM Engines
- External APIs (OpenAI)
- Local models (Llama2, Qwen, Baichuan via vLLM, quantized binary)
5. Tooling Modules
- Index Advisor, Query Rewrite, Physical Hint, Metric Monitor
- Document loaders + chunking + embedding (`document_loaders/`, `text_splitter/`)
6. Monitoring & Anomaly Simulator
- Prometheus (metrics exporter)
- Alertmanager (alert rules)
- Python webhook (records alerts)
- Anomaly generator scripts (`anomaly_trigger/`)
7. Configuration & Deployment
- Docker Compose for monitoring services
- Config files (`configs/`, `.env`, `server_config.py`)
- Startup scripts (`startup.py`, `shutdown_all.sh`)
- User → Web UI → HTTP API → Backend
- Backend → Knowledge-base (vector DB) → returns relevant docs
- Backend → Multi-agent orchestrator → selects tools & LLM engines
- Orchestrator → LLM Engines / Tools → produces analysis or Q&A → Backend
- Backend → PostgreSQL → stores chat history & feedback
- Prometheus → scrapes DB & app metrics → Alertmanager → Python webhook → writes alert files → Backend (diagnosis input)
- Anomaly Trigger Scripts → produce synthetic load on DB → metrics → Prometheus → alerts
c. Architectural Patterns & Principles
- Modular microservices: monitoring stack decoupled via Docker Compose
- Layered architecture: UI / API / domain logic / persistence
- Adapter pattern: pluggable LLM backends & knowledge storage
- Multi-agent orchestration: dispatch-review-summarize chain
- RAG (Retrieval Augmented Generation) for grounded answers
d. Technologies & Frameworks
- Backend: Python 3.10+, FastAPI, SQLAlchemy, Uvicorn, Streamlit
- Frontend: Vue3, Vite, Element-Plus, TypeScript
- Vector DB: Chroma, FAISS, Milvus, Elasticsearch
- LLMs: OpenAI API, vLLM, HuggingFace models, quantized Baichuan2
- Monitoring: Prometheus, node_exporter, postgres_exporter, Alertmanager
- Deployment: Docker, Docker Compose, shell scripts

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        WebUI["Vue3 Web UI"]:::frontend
        Streamlit["Streamlit Apps"]:::frontend
    end

    %% API Gateway & Orchestration
    subgraph "API & Orchestration" 
        direction TB
        API["FastAPI Backend"]:::backend
        EmbeddingsAPI["Embeddings API"]:::backend
        LLMAPI["LLM API"]:::backend
        Orchestrator["Multi-Agent Orchestrator"]:::backend
    end

    %% Processing & Tools
    subgraph "Processing & Tools"
        direction TB
        KBService["Knowledge-Base Service"]:::backend
        DocIngest["Document Ingestion & Chunking"]:::backend
        Tools["Tooling Modules"]:::backend
        LLMAdapters["LLM Adapters"]:::external
    end

    %% Storage Layer
    subgraph "Storage Layer"
        direction TB
        VectorDB["Vector Store"]:::storage
        Postgres["PostgreSQL"]:::storage
    end

    %% Monitoring & Anomaly
    subgraph "Monitoring & Anomaly"
        direction TB
        Prometheus["Prometheus"]:::monitor
        Alertmanager["Alertmanager"]:::monitor
        Webhook["Python Webhook"]:::monitor
        AnomalySim["Anomaly Simulation Scripts"]:::monitor
    end

    %% Flows
    WebUI -->|"HTTP Request"| API
    Streamlit -->|"HTTP Request"| API

    API -->|"calls"| EmbeddingsAPI
    API -->|"calls"| LLMAPI
    API -->|"invokes"| Orchestrator

    Orchestrator -->|"uses"| KBService
    Orchestrator -->|"dispatches to"| LLMAdapters
    Orchestrator -->|"invokes"| Tools
    Orchestrator -->|"uses"| DocIngest

    KBService -->|"queries"| VectorDB
    API -->|"reads/writes"| Postgres

    Prometheus -->|"scrapes metrics"| Postgres
    Prometheus -->|"scrapes metrics"| API
    Prometheus -->|"alerts"| Alertmanager
    Alertmanager -->|".webhook"| Webhook
    Webhook -->|"async alert"| API

    AnomalySim -->|"synthetic load"| Postgres
    AnomalySim -->|"metrics"| Prometheus

    %% Click Events for component mapping
    click WebUI "https://github.com/tsinghuadatabasegroup/db-gpt/tree/main/webui/"
    click Streamlit "https://github.com/tsinghuadatabasegroup/db-gpt/tree/main/webui_pages/"
    click API "https://github.com/tsinghuadatabasegroup/db-gpt/blob/main/server/api.py"
    click EmbeddingsAPI "https://github.com/tsinghuadatabasegroup/db-gpt/blob/main/server/embeddings_api.py"
    click LLMAPI "https://github.com/tsinghuadatabasegroup/db-gpt/blob/main/server/llm_api.py"
    click Orchestrator "https://github.com/tsinghuadatabasegroup/db-gpt/blob/main/multiagents/initialization.py"
    click KBService "https://github.com/tsinghuadatabasegroup/db-gpt/blob/main/server/knowledge_base/kb_api.py"
    click DocIngest "https://github.com/tsinghuadatabasegroup/db-gpt/tree/main/document_loaders/"
    click Tools "https://github.com/tsinghuadatabasegroup/db-gpt/tree/main/multiagents/tools/"
    click LLMAdapters "https://github.com/tsinghuadatabasegroup/db-gpt/tree/main/multiagents/llms/"
    click Postgres "https://github.com/tsinghuadatabasegroup/db-gpt/blob/main/server/db/session.py"
    click VectorDB "https://github.com/tsinghuadatabasegroup/db-gpt/blob/main/server/knowledge_base/kb_service/chroma_kb_service.py"
    click AnomalySim "https://github.com/tsinghuadatabasegroup/db-gpt/tree/main/anomaly_trigger/"
    click Prometheus "https://github.com/tsinghuadatabasegroup/db-gpt/blob/main/prometheus_service_docker/docker-compose.yml"
    click Alertmanager "https://github.com/tsinghuadatabasegroup/db-gpt/blob/main/prometheus_service_docker/alertmanager.yml"
    click Webhook "https://github.com/tsinghuadatabasegroup/db-gpt/blob/main/prometheus_service_docker/app.py"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#21618C,color:#1B2631;
    classDef backend fill:#ABEBC6,stroke:#196F3D,color:#1B2631;
    classDef storage fill:#F9E79F,stroke:#B9770E,color:#1B2631;
    classDef monitor fill:#F5B7B1,stroke:#943126,color:#1B2631;
    classDef external fill:#D2B4DE,stroke:#6C3483,color:#1B2631;
```
