# jumpserver/chen architecture

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

- Interactive diagram: https://gitdiagram.com/jumpserver/chen
- Repository: https://github.com/jumpserver/chen

## Overview

Chen is JumpServer’s Java WebDB connection component: it authenticates a user, establishes a database session (optionally through Wisp), and provides SQL-console, metadata, resource-browsing, and table-editing capabilities across multiple database protocols. The graph highlights those product stages and the execution-plan and transaction-aware edit layers. Some web routing and capability wiring is unsampled; those relationships are omitted or shown as unverified rather than inferred as confirmed calls.

Main entry points: [`backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/Datasource.java`](https://github.com/jumpserver/chen/blob/dev/backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/Datasource.java) (Datasource facade), [`backend/web/src/main/java/org/jumpserver/chen/web/service/impl/JmsSessionService.java`](https://github.com/jumpserver/chen/blob/dev/backend/web/src/main/java/org/jumpserver/chen/web/service/impl/JmsSessionService.java) (Session setup), [`backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/base/BaseConnectionManager.java`](https://github.com/jumpserver/chen/blob/dev/backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/base/BaseConnectionManager.java) (Connection manager), [`backend/web/src/main/java/org/jumpserver/chen/web/ai/SqlAgentToolService.java`](https://github.com/jumpserver/chen/blob/dev/backend/web/src/main/java/org/jumpserver/chen/web/ai/SqlAgentToolService.java) (SQL assistant tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and sessions"]
  node_webapi["Web API"]
  node_sessionservice["Session setup"]
  node_sessions[("Session registry")]
  node_session["Database session<br/>[Session.java]"]
end

subgraph group_console["SQL console"]
  node_sqlagent["SQL assistant tools"]
  node_queryconsole["Query console<br/>[QueryConsole.java]"]
  node_plans["Plan analysis"]
end

subgraph group_database["Database access"]
  node_datasource["Datasource facade<br/>[Datasource.java]"]
  node_connections["Connection manager"]
  node_metadata[("Metadata catalog")]
  node_sqlmetadata["SQL metadata"]
  node_resourceapi["Resource browsing"]
end

subgraph group_editing["Table editing"]
  node_preview["Edit preview"]
  node_editplan["Change planning"]
  node_save["Change saving"]
end

subgraph group_integrations["Database integrations"]
  node_wisp["Wisp service<br/>[ServiceGrpc.java]"]
  node_mysql["MySQL driver"]
  node_dbprotocols["Other database modules"]
end

node_user(("WebDB user"))
node_externaldb[("Database server")]

node_user -.->|"requests access"| node_webapi
node_webapi -.->|"starts session"| node_sessionservice
node_sessionservice -->|"creates tunnel"| node_wisp
node_sessionservice -->|"builds datasource"| node_datasource
node_sessionservice -->|"creates session"| node_session
node_sessions -->|"stores sessions"| node_session
node_sessions -->|"registers console"| node_queryconsole
node_sqlagent -->|"uses console"| node_queryconsole
node_sqlagent -->|"inspects database"| node_datasource
node_sqlagent -->|"reads metadata"| node_metadata
node_plans -->|"analyzes SQL"| node_datasource
node_datasource -->|"provides connections"| node_connections
node_connections -.->|"opens JDBC"| node_externaldb
node_metadata -->|"sets database context"| node_connections
node_sqlmetadata -->|"loads relations"| node_metadata
node_resourceapi -.->|"browses resources"| node_datasource
node_preview -->|"builds preview"| node_editplan
node_save -.->|"applies plan"| node_editplan
node_mysql -->|"extends manager"| node_connections
node_dbprotocols -.->|"implements protocols"| node_datasource
node_queryconsole -.->|"audited SQL"| node_session

click node_webapi "https://github.com/jumpserver/chen/tree/dev/backend/web/src/main/java/org/jumpserver/chen/web/controller"
click node_sessionservice "https://github.com/jumpserver/chen/blob/dev/backend/web/src/main/java/org/jumpserver/chen/web/service/impl/JmsSessionService.java"
click node_sessions "https://github.com/jumpserver/chen/blob/dev/backend/framework/src/main/java/org/jumpserver/chen/framework/session/SessionManager.java"
click node_session "https://github.com/jumpserver/chen/blob/dev/backend/framework/src/main/java/org/jumpserver/chen/framework/session/Session.java"
click node_wisp "https://github.com/jumpserver/chen/blob/dev/backend/wisp/src/main/java/org/jumpserver/wisp/ServiceGrpc.java"
click node_sqlagent "https://github.com/jumpserver/chen/blob/dev/backend/web/src/main/java/org/jumpserver/chen/web/ai/SqlAgentToolService.java"
click node_queryconsole "https://github.com/jumpserver/chen/blob/dev/backend/framework/src/main/java/org/jumpserver/chen/framework/console/QueryConsole.java"
click node_plans "https://github.com/jumpserver/chen/blob/dev/backend/framework/src/main/java/org/jumpserver/chen/framework/console/plan/ExecutionPlanService.java"
click node_datasource "https://github.com/jumpserver/chen/blob/dev/backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/Datasource.java"
click node_connections "https://github.com/jumpserver/chen/blob/dev/backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/base/BaseConnectionManager.java"
click node_metadata "https://github.com/jumpserver/chen/blob/dev/backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/metadata/MetadataCatalog.java"
click node_sqlmetadata "https://github.com/jumpserver/chen/blob/dev/backend/web/src/main/java/org/jumpserver/chen/web/service/SqlMetadataService.java"
click node_resourceapi "https://github.com/jumpserver/chen/blob/dev/backend/web/src/main/java/org/jumpserver/chen/web/service/ResourceService.java"
click node_preview "https://github.com/jumpserver/chen/blob/dev/backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/edit/TableChangesPreviewService.java"
click node_editplan "https://github.com/jumpserver/chen/blob/dev/backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/edit/TableChangesPlanBuilder.java"
click node_save "https://github.com/jumpserver/chen/blob/dev/backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/edit/TableChangesSaveService.java"
click node_mysql "https://github.com/jumpserver/chen/blob/dev/backend/modules/src/main/java/org.jumpserver.chen.modules/mysql/MysqlConnectionManager.java"
click node_dbprotocols "https://github.com/jumpserver/chen/tree/dev/backend/modules/src/main/java/org.jumpserver.chen.modules"

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_webapi,node_sessionservice,node_sessions,node_session,node_user toneBlue
class node_sqlagent,node_queryconsole,node_plans,node_externaldb toneAmber
class node_datasource,node_connections,node_metadata,node_sqlmetadata,node_resourceapi toneMint
class node_preview,node_editplan,node_save toneRose
class node_wisp,node_mysql,node_dbprotocols toneIndigo
```

## Components

### Access and sessions

- [Web API](https://github.com/jumpserver/chen/tree/dev/backend/web/src/main/java/org/jumpserver/chen/web/controller): `backend/web/src/main/java/org/jumpserver/chen/web/controller`
- [Session setup](https://github.com/jumpserver/chen/blob/dev/backend/web/src/main/java/org/jumpserver/chen/web/service/impl/JmsSessionService.java): `backend/web/src/main/java/org/jumpserver/chen/web/service/impl/JmsSessionService.java`
- [Session registry](https://github.com/jumpserver/chen/blob/dev/backend/framework/src/main/java/org/jumpserver/chen/framework/session/SessionManager.java): `backend/framework/src/main/java/org/jumpserver/chen/framework/session/SessionManager.java`
- [Database session](https://github.com/jumpserver/chen/blob/dev/backend/framework/src/main/java/org/jumpserver/chen/framework/session/Session.java): `backend/framework/src/main/java/org/jumpserver/chen/framework/session/Session.java`

### SQL console

- [SQL assistant tools](https://github.com/jumpserver/chen/blob/dev/backend/web/src/main/java/org/jumpserver/chen/web/ai/SqlAgentToolService.java): `backend/web/src/main/java/org/jumpserver/chen/web/ai/SqlAgentToolService.java`
- [Query console](https://github.com/jumpserver/chen/blob/dev/backend/framework/src/main/java/org/jumpserver/chen/framework/console/QueryConsole.java): `backend/framework/src/main/java/org/jumpserver/chen/framework/console/QueryConsole.java`
- [Plan analysis](https://github.com/jumpserver/chen/blob/dev/backend/framework/src/main/java/org/jumpserver/chen/framework/console/plan/ExecutionPlanService.java): `backend/framework/src/main/java/org/jumpserver/chen/framework/console/plan/ExecutionPlanService.java`

### Database access

- [Datasource facade](https://github.com/jumpserver/chen/blob/dev/backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/Datasource.java): `backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/Datasource.java`
- [Connection manager](https://github.com/jumpserver/chen/blob/dev/backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/base/BaseConnectionManager.java): `backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/base/BaseConnectionManager.java`
- [Metadata catalog](https://github.com/jumpserver/chen/blob/dev/backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/metadata/MetadataCatalog.java): `backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/metadata/MetadataCatalog.java`
- [SQL metadata](https://github.com/jumpserver/chen/blob/dev/backend/web/src/main/java/org/jumpserver/chen/web/service/SqlMetadataService.java): `backend/web/src/main/java/org/jumpserver/chen/web/service/SqlMetadataService.java`
- [Resource browsing](https://github.com/jumpserver/chen/blob/dev/backend/web/src/main/java/org/jumpserver/chen/web/service/ResourceService.java): `backend/web/src/main/java/org/jumpserver/chen/web/service/ResourceService.java`

### Table editing

- [Edit preview](https://github.com/jumpserver/chen/blob/dev/backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/edit/TableChangesPreviewService.java): `backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/edit/TableChangesPreviewService.java`
- [Change planning](https://github.com/jumpserver/chen/blob/dev/backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/edit/TableChangesPlanBuilder.java): `backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/edit/TableChangesPlanBuilder.java`
- [Change saving](https://github.com/jumpserver/chen/blob/dev/backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/edit/TableChangesSaveService.java): `backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/edit/TableChangesSaveService.java`

### Database integrations

- [Wisp service](https://github.com/jumpserver/chen/blob/dev/backend/wisp/src/main/java/org/jumpserver/wisp/ServiceGrpc.java): `backend/wisp/src/main/java/org/jumpserver/wisp/ServiceGrpc.java`
- [MySQL driver](https://github.com/jumpserver/chen/blob/dev/backend/modules/src/main/java/org.jumpserver.chen.modules/mysql/MysqlConnectionManager.java): `backend/modules/src/main/java/org.jumpserver.chen.modules/mysql/MysqlConnectionManager.java`
- [Other database modules](https://github.com/jumpserver/chen/tree/dev/backend/modules/src/main/java/org.jumpserver.chen.modules): `backend/modules/src/main/java/org.jumpserver.chen.modules`

### Other components

- **WebDB user**
- **Database server**

## Connections

- WebDB user → Web API: requests access
- Web API → Session setup: starts session
- Session setup → Wisp service: creates tunnel (evidence: `backend/web/src/main/java/org/jumpserver/chen/web/service/impl/JmsSessionService.java`)
- Session setup → Datasource facade: builds datasource (evidence: `backend/web/src/main/java/org/jumpserver/chen/web/service/impl/JmsSessionService.java`)
- Session setup → Database session: creates session (evidence: `backend/web/src/main/java/org/jumpserver/chen/web/service/impl/JmsSessionService.java`)
- Session registry → Database session: stores sessions (evidence: `backend/framework/src/main/java/org/jumpserver/chen/framework/session/SessionManager.java`)
- Session registry → Query console: registers console (evidence: `backend/framework/src/main/java/org/jumpserver/chen/framework/session/SessionManager.java`)
- SQL assistant tools → Query console: uses console (evidence: `backend/web/src/main/java/org/jumpserver/chen/web/ai/SqlAgentToolService.java`)
- SQL assistant tools → Datasource facade: inspects database (evidence: `backend/web/src/main/java/org/jumpserver/chen/web/ai/SqlAgentToolService.java`)
- SQL assistant tools → Metadata catalog: reads metadata (evidence: `backend/web/src/main/java/org/jumpserver/chen/web/ai/SqlAgentToolService.java`)
- Plan analysis → Datasource facade: analyzes SQL (evidence: `backend/framework/src/main/java/org/jumpserver/chen/framework/console/plan/ExecutionPlanService.java`)
- Datasource facade → Connection manager: provides connections (evidence: `backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/base/BaseConnectionManager.java`)
- Connection manager → Database server: opens JDBC
- Metadata catalog → Connection manager: sets database context (evidence: `backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/metadata/MetadataCatalog.java`)
- SQL metadata → Metadata catalog: loads relations (evidence: `backend/web/src/main/java/org/jumpserver/chen/web/service/SqlMetadataService.java`)
- Resource browsing → Datasource facade: browses resources (evidence: `backend/web/src/main/java/org/jumpserver/chen/web/service/ResourceService.java`)
- Edit preview → Change planning: builds preview (evidence: `backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/edit/TableChangesPreviewService.java`)
- Change saving → Change planning: applies plan (evidence: `backend/framework/src/main/java/org/jumpserver/chen/framework/datasource/edit/TableChangesSaveService.java`)
- MySQL driver → Connection manager: extends manager (evidence: `backend/modules/src/main/java/org.jumpserver.chen.modules/mysql/MysqlConnectionManager.java`)
- Other database modules → Datasource facade: implements protocols (evidence: `backend/modules/src/main/java/org.jumpserver.chen.modules/mysql/MysqlConnectionManager.java`)
- Query console → Database session: audited SQL
