# t8y2/dbx architecture

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

- Interactive diagram: https://gitdiagram.com/t8y2/dbx
- Repository: https://github.com/t8y2/dbx
- Video tour (about a minute): https://gitdiagram.com/t8y2/dbx/video

## Overview

DBX is a multi-database client and management platform, offered as desktop, Docker/web, CLI, AI assistant, and MCP server. Its principal workflow is a user composing and executing database work, with DBX routing it through shared query and driver layers to a connected database and presenting results. The repository also documents schema, backup, administration, and plugin capabilities. Edges use the README or shown source-index references; several subsystem links are necessarily broad because their implementation was not sampled.

Main entry points: [`crates/dbx-sql-core/src/query_execution_sql.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-sql-core/src/query_execution_sql.rs) (Query execution), [`crates/dbx-driver-agent/src/agent_runtime.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-driver-agent/src/agent_runtime.rs) (Driver runtime), [`apps/desktop/src/App.vue`](https://github.com/t8y2/dbx/blob/main/apps/desktop/src/App.vue) (Desktop app), [`apps/desktop/src/components/editor/useQueryEditorCompletion.ts`](https://github.com/t8y2/dbx/blob/main/apps/desktop/src/components/editor/useQueryEditorCompletion.ts) (SQL editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop client"]
  node_desktop_app["Desktop app<br/>[App.vue]"]
  node_sql_editor["SQL editor"]
  node_completion_metadata["Completion metadata"]
  node_schema_diagram["Schema diagrams"]
  node_schema_diff["Schema comparison"]
  node_admin_ui["Database administration"]
end

subgraph group_core["Query and drivers"]
  node_query_core["Query execution"]
  node_sql_core["SQL handling<br/>[sql.rs]"]
  node_query_results["Result export"]
  node_agent_manager["Driver management<br/>[agent_manager.rs]"]
  node_agent_runtime["Driver runtime<br/>[agent_runtime.rs]"]
  node_jdbc_protocol["Agent protocol<br/>[AgentProtocol.java]"]
end

subgraph group_services["Services and interfaces"]
  node_web_server["Web service<br/>[main.rs]"]
  node_web_query["Web query routes<br/>[query.rs]"]
  node_scheduled_backup["Scheduled backups<br/>[engine.rs]"]
  node_cli["Command-line client<br/>[main.rs]"]
  node_mcp_server["MCP server<br/>[server.rs]"]
  node_mcp_backend["MCP backend<br/>[backend.rs]"]
end

subgraph group_extensions["Plugins and AI"]
  node_plugin_host["Plugin host<br/>[server.mjs]"]
  node_plugin_storage[("Plugin storage<br/>[plugin_storage.rs]")]
  node_ai_assistant["Built-in AI"]
end

node_user(("Database user"))
node_database[("Connected databases")]

node_user -->|"uses"| node_desktop_app
node_desktop_app -.->|"provides editor"| node_sql_editor
node_sql_editor -->|"loads metadata"| node_completion_metadata
node_user -.->|"runs queries"| node_query_core
node_query_core -->|"uses SQL handling"| node_sql_core
node_query_core -.->|"executes against"| node_database
node_query_core -.->|"exports results"| node_query_results
node_agent_manager -->|"manages runtime"| node_agent_runtime
node_agent_runtime -.->|"connects through agents"| node_database
node_agent_runtime -.->|"launches agents"| node_jdbc_protocol
node_user -->|"uses web edition"| node_web_server
node_web_server -->|"routes requests"| node_web_query
node_web_query -.->|"uses query services"| node_query_core
node_user -->|"uses CLI"| node_cli
node_user -->|"uses MCP"| node_mcp_server
node_mcp_server -->|"delegates tools"| node_mcp_backend
node_user -.->|"configures backups"| node_scheduled_backup
node_scheduled_backup -.->|"exports data"| node_query_results
node_user -->|"explores schema"| node_schema_diagram
node_user -->|"compares schemas"| node_schema_diff
node_user -->|"administers databases"| node_admin_ui
node_user -->|"uses assistant"| node_ai_assistant
node_user -.->|"uses plugins"| node_plugin_host
node_plugin_host -.->|"stores plugin state"| node_plugin_storage

click node_desktop_app "https://github.com/t8y2/dbx/blob/main/apps/desktop/src/App.vue"
click node_sql_editor "https://github.com/t8y2/dbx/blob/main/apps/desktop/src/components/editor/useQueryEditorCompletion.ts"
click node_completion_metadata "https://github.com/t8y2/dbx/blob/main/apps/desktop/src/components/editor/useQueryEditorCompletionMetadata.ts"
click node_schema_diagram "https://github.com/t8y2/dbx/blob/main/apps/desktop/src/components/diagram/SchemaDiagramDialog.vue"
click node_schema_diff "https://github.com/t8y2/dbx/blob/main/apps/desktop/src/components/diff/SchemaDiffDialog.vue"
click node_admin_ui "https://github.com/t8y2/dbx/blob/main/apps/desktop/src/components/admin/DatabaseUserAdmin.vue"
click node_query_core "https://github.com/t8y2/dbx/blob/main/crates/dbx-sql-core/src/query_execution_sql.rs"
click node_sql_core "https://github.com/t8y2/dbx/blob/main/crates/dbx-sql-core/src/sql.rs"
click node_query_results "https://github.com/t8y2/dbx/blob/main/crates/dbx-core/src/data/query_result_export.rs"
click node_agent_manager "https://github.com/t8y2/dbx/blob/main/crates/dbx-driver-agent/src/agent_manager.rs"
click node_agent_runtime "https://github.com/t8y2/dbx/blob/main/crates/dbx-driver-agent/src/agent_runtime.rs"
click node_jdbc_protocol "https://github.com/t8y2/dbx/blob/main/agents/common/src/main/java/com/dbx/agent/AgentProtocol.java"
click node_web_server "https://github.com/t8y2/dbx/blob/main/crates/dbx-web/src/main.rs"
click node_web_query "https://github.com/t8y2/dbx/blob/main/crates/dbx-web/src/routes/query.rs"
click node_scheduled_backup "https://github.com/t8y2/dbx/blob/main/crates/dbx-core/src/scheduled_backup/engine.rs"
click node_cli "https://github.com/t8y2/dbx/blob/main/crates/dbx-cli/src/main.rs"
click node_mcp_server "https://github.com/t8y2/dbx/blob/main/crates/dbx-mcp/src/server.rs"
click node_mcp_backend "https://github.com/t8y2/dbx/blob/main/crates/dbx-mcp/src/backend.rs"
click node_plugin_host "https://github.com/t8y2/dbx/blob/main/plugins/sdk/dev-host/server.mjs"
click node_plugin_storage "https://github.com/t8y2/dbx/blob/main/src-tauri/src/commands/plugin_storage.rs"
click node_ai_assistant "https://github.com/t8y2/dbx/blob/main/apps/desktop/src/components/ai/rich/AiChartRenderer.vue"

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_desktop_app,node_sql_editor,node_completion_metadata,node_schema_diagram,node_schema_diff,node_admin_ui toneBlue
class node_query_core,node_sql_core,node_query_results,node_agent_manager,node_agent_runtime,node_jdbc_protocol,node_user,node_database toneAmber
class node_web_server,node_web_query,node_scheduled_backup,node_cli,node_mcp_server,node_mcp_backend toneMint
class node_plugin_host,node_plugin_storage,node_ai_assistant toneRose
```

## Components

### Desktop client

- [Desktop app](https://github.com/t8y2/dbx/blob/main/apps/desktop/src/App.vue): `apps/desktop/src/App.vue`
- [SQL editor](https://github.com/t8y2/dbx/blob/main/apps/desktop/src/components/editor/useQueryEditorCompletion.ts): `apps/desktop/src/components/editor/useQueryEditorCompletion.ts`
- [Completion metadata](https://github.com/t8y2/dbx/blob/main/apps/desktop/src/components/editor/useQueryEditorCompletionMetadata.ts): `apps/desktop/src/components/editor/useQueryEditorCompletionMetadata.ts`
- [Schema diagrams](https://github.com/t8y2/dbx/blob/main/apps/desktop/src/components/diagram/SchemaDiagramDialog.vue): `apps/desktop/src/components/diagram/SchemaDiagramDialog.vue`
- [Schema comparison](https://github.com/t8y2/dbx/blob/main/apps/desktop/src/components/diff/SchemaDiffDialog.vue): `apps/desktop/src/components/diff/SchemaDiffDialog.vue`
- [Database administration](https://github.com/t8y2/dbx/blob/main/apps/desktop/src/components/admin/DatabaseUserAdmin.vue): `apps/desktop/src/components/admin/DatabaseUserAdmin.vue`

### Query and drivers

- [Query execution](https://github.com/t8y2/dbx/blob/main/crates/dbx-sql-core/src/query_execution_sql.rs): `crates/dbx-sql-core/src/query_execution_sql.rs`
- [SQL handling](https://github.com/t8y2/dbx/blob/main/crates/dbx-sql-core/src/sql.rs): `crates/dbx-sql-core/src/sql.rs`
- [Result export](https://github.com/t8y2/dbx/blob/main/crates/dbx-core/src/data/query_result_export.rs): `crates/dbx-core/src/data/query_result_export.rs`
- [Driver management](https://github.com/t8y2/dbx/blob/main/crates/dbx-driver-agent/src/agent_manager.rs): `crates/dbx-driver-agent/src/agent_manager.rs`
- [Driver runtime](https://github.com/t8y2/dbx/blob/main/crates/dbx-driver-agent/src/agent_runtime.rs): `crates/dbx-driver-agent/src/agent_runtime.rs`
- [Agent protocol](https://github.com/t8y2/dbx/blob/main/agents/common/src/main/java/com/dbx/agent/AgentProtocol.java): `agents/common/src/main/java/com/dbx/agent/AgentProtocol.java`

### Services and interfaces

- [Web service](https://github.com/t8y2/dbx/blob/main/crates/dbx-web/src/main.rs): `crates/dbx-web/src/main.rs`
- [Web query routes](https://github.com/t8y2/dbx/blob/main/crates/dbx-web/src/routes/query.rs): `crates/dbx-web/src/routes/query.rs`
- [Scheduled backups](https://github.com/t8y2/dbx/blob/main/crates/dbx-core/src/scheduled_backup/engine.rs): `crates/dbx-core/src/scheduled_backup/engine.rs`
- [Command-line client](https://github.com/t8y2/dbx/blob/main/crates/dbx-cli/src/main.rs): `crates/dbx-cli/src/main.rs`
- [MCP server](https://github.com/t8y2/dbx/blob/main/crates/dbx-mcp/src/server.rs): `crates/dbx-mcp/src/server.rs`
- [MCP backend](https://github.com/t8y2/dbx/blob/main/crates/dbx-mcp/src/backend.rs): `crates/dbx-mcp/src/backend.rs`

### Plugins and AI

- [Plugin host](https://github.com/t8y2/dbx/blob/main/plugins/sdk/dev-host/server.mjs): `plugins/sdk/dev-host/server.mjs`
- [Plugin storage](https://github.com/t8y2/dbx/blob/main/src-tauri/src/commands/plugin_storage.rs): `src-tauri/src/commands/plugin_storage.rs`
- [Built-in AI](https://github.com/t8y2/dbx/blob/main/apps/desktop/src/components/ai/rich/AiChartRenderer.vue): `apps/desktop/src/components/ai/rich/AiChartRenderer.vue`

### Other components

- **Database user**
- **Connected databases**

## Connections

- Database user → Desktop app: uses
- Desktop app → SQL editor: provides editor
- SQL editor → Completion metadata: loads metadata (evidence: `apps/desktop/src/components/editor/useQueryEditorCompletion.ts`)
- Database user → Query execution: runs queries
- Query execution → SQL handling: uses SQL handling (evidence: `crates/dbx-sql-core/src/query_execution_sql.rs`)
- Query execution → Connected databases: executes against
- Query execution → Result export: exports results
- Driver management → Driver runtime: manages runtime (evidence: `crates/dbx-driver-agent/src/agent_manager.rs`)
- Driver runtime → Connected databases: connects through agents
- Driver runtime → Agent protocol: launches agents
- Database user → Web service: uses web edition
- Web service → Web query routes: routes requests (evidence: `crates/dbx-web/src/main.rs`)
- Web query routes → Query execution: uses query services
- Database user → Command-line client: uses CLI
- Database user → MCP server: uses MCP
- MCP server → MCP backend: delegates tools (evidence: `crates/dbx-mcp/src/server.rs`)
- Database user → Scheduled backups: configures backups
- Scheduled backups → Result export: exports data
- Database user → Schema diagrams: explores schema
- Database user → Schema comparison: compares schemas
- Database user → Database administration: administers databases
- Database user → Built-in AI: uses assistant
- Database user → Plugin host: uses plugins
- Plugin host → Plugin storage: stores plugin state
