Chat2DB Backend Architecture: A Deep Dive into the Modular Spring Boot Design

Chat2DB's backend is a modular, Spring Boot-based Java 17 application organized into distinct layers: bootstrap, web API, service/SPI, domain, storage, and database-specific plugins.

The Chat2DB backend, maintained in the OtterMind/Chat2DB repository, powers an AI-driven database client with a clean, layered architecture. Built on Java 17 and Spring Boot, the codebase separates concerns into independent Maven modules, making it straightforward to extend with new database dialects or storage backends.

Architectural Layers

Bootstrap Layer

The bootstrap layer initializes the Spring context and wires all modules together. The entry point is the [Application.java](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/chat2db-community-start/src/main/java/ai/chat2db/community/start/Application.java) class located in the chat2db-community-start module. This class scans the classpath and registers Spring beans across the entire application.

Web API Layer

Controllers and request/response DTOs reside in chat2db-community-web. The [RequestMappingUtils.java](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/chat2db-community-web/src/main/java/ai/chat2db/community/web/api/util/RequestMappingUtils.java) utility scans @RestController beans to build routing metadata, exposing REST endpoints for the UI and external clients.

Service and SPI Layer

The chat2db-community-spi module contains core business logic, SQL parsing, and database abstraction. Key classes include:

• [Chat2DBContext.java](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/chat2db-community-spi/src/main/java/ai/chat2db/spi/sql/Chat2DBContext.java) – Holds per-request context including datasource configurations, connection pools, and execution metrics.
• [JdbcUtils.java](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/chat2db-community-spi/src/main/java/ai/chat2db/spi/util/JdbcUtils.java) – Provides helper methods for JDBC connection handling and result-set conversion.

This layer acts as the intermediary between the REST controllers and the underlying database implementations.

Domain Layer

The chat2db-community-domain module defines the core domain model (tables, schemas, tasks, and logs) and high-level service contracts. It is split into chat2db-community-domain-core and chat2db-community-domain-api sub-modules to separate implementation from interfaces.

Storage Layer

Workspace data, execution logs, and binary large objects are managed in chat2db-community-storage. This layer provides:

• SmallDataStorage – Handles lightweight metadata.
• LargeDataStorage – Manages large result sets and binary cells.
• [LocalWorkspaceStorageProvider.java](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/chat2db-community-storage/src/main/java/ai/chat2db/community/storage/LocalWorkspaceStorageProvider.java) – The default implementation for persisting workspace state to local storage.

Execution history is specifically handled by [OperationLogStorage.java](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/chat2db-community-storage/src/main/java/ai/chat2db/community/storage/large/OperationLogStorage.java), which persists query logs in the large storage layer.

Plugin Architecture

Database-specific implementations live in chat2db-community-plugins, with each dialect residing in its own sub-module. Examples include:

• [MariaDBSqlParser.java](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/chat2db-community-plugins/chat2db-community-mariadb/src/main/java/ai/chat2db/plugin/mariadb/parser/MariadbSqlParser.java) – Parses MariaDB-specific SQL syntax.
• [ElasticSearchParser.java](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/chat2db-community-plugins/chat2db-community-elasticsearch/src/main/java/ai/chat2db/plugin/elasticsearch/parser/ElasticSearchParser.java) – Demonstrates support for non-relational databases.

Plugins register via the SPI using Spring's @ConditionalOnClass mechanism and @AutoService(Plugin.class) annotations.

JCEF Integration

For desktop deployments, the chat2db-community-jcef module bridges the Java backend to the Chromium Embedded Framework (CEF) renderer. The [JcefBridge.java](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/chat2db-community-jcef/src/main/java/ai/chat2db/jcef/JcefBridge.java) class exposes a Java-to-JavaScript bridge (window.javaQuery), allowing the desktop UI to invoke backend methods directly while maintaining the same REST API compatibility.

How the Layers Interact

1. Bootstrap – Application.java launches Spring Boot, scans the classpath, and registers all modules.
2. Web – Controllers receive HTTP requests (e.g., /api/sql/execute) and delegate to SPI beans.
3. Service – SQLExecutor and Chat2DBContext build logical execution plans using the Domain model.
4. Storage – The Storage layer persists workspace state, operation logs, and result sets via LocalWorkspaceStorageProvider and OperationLogStorage.
5. Plugin – When a specific database dialect is required, the SPI looks up the appropriate plugin (e.g., MariaDBSqlParser) to handle parsing and value processing.

Running the Backend

To build and start the backend in development mode:

mvn -B clean package -Dchat2db.runtime.mode=community -Dchat2db.finalName=chat2db-community -pl chat2db-community-start -am
java -Dloader.path=chat2db-community-server/chat2db-community-start/target/lib \
     -Dchat2db.gui=false \
     -Dchat2db.runtime.mode=community \
     -Dchat2db.network.status=OFFLINE \
     -Dserver.address=127.0.0.1 \
     -Dserver.port=10825 \
     -jar chat2db-community-server/chat2db-community-start/target/chat2db-community.jar

Execute a SQL statement via the REST API:

curl -X POST http://127.0.0.1:10825/api/sql/execute \
     -H "Content-Type: application/json" \
     -d '{"dataSourceId":1,"sql":"SELECT * FROM users LIMIT 10"}'

Extending with Custom Plugins

To add a new database dialect, create a Maven module in chat2db-community-plugins with the following dependency:

<dependency>
    <groupId>ai.chat2db</groupId>
    <artifactId>chat2db-community-spi</artifactId>
    <version>${project.version}</version>
</dependency>

Then implement the plugin entry point:

@AutoService(Plugin.class)
public class MyDbPlugin implements Plugin {
    @Override
    public void register(PluginRegistry registry) {
        registry.registerSqlParser(MyDbSqlParser.class);
        registry.registerValueProcessor(MyDbValueProcessorFactory.class);
    }
}

Summary

• Chat2DB uses a layered Spring Boot architecture with clear separation between web, service, domain, storage, and plugin concerns.
• The SPI module (chat2db-community-spi) provides the core abstraction for database operations via Chat2DBContext and JdbcUtils, while plugins supply dialect-specific implementations.
• Storage is bifurcated into small (metadata) and large (BLOBs/result sets) implementations managed by LocalWorkspaceStorageProvider.
• The JCEF module enables desktop integration by bridging Java backend logic to the Chromium renderer through JcefBridge.
• All modules are independent Maven projects, enabling selective builds and third-party plugin integration via the @AutoService pattern.

Frequently Asked Questions

What Java version does Chat2DB require?

Chat2DB requires Java 17 or higher. The Spring Boot application targets Java 17 bytecode, ensuring compatibility with modern language features while maintaining runtime stability across supported platforms.

How does Chat2DB support multiple database dialects?

The backend uses a Service Provider Interface (SPI) pattern. Each database dialect (MySQL, PostgreSQL, MariaDB, etc.) is implemented as a separate Maven module in chat2db-community-plugins. Each plugin implements parser and value processor interfaces, registering automatically via @AutoService(Plugin.class) annotations, allowing the core SPI to delegate dialect-specific operations without hard-coded dependencies.

Where does Chat2DB store execution history and workspace data?

Execution logs and large result sets are stored via the Storage layer in chat2db-community-storage. Specifically, [OperationLogStorage.java](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/chat2db-community-storage/src/main/java/ai/chat2db/community/storage/large/OperationLogStorage.java) handles persistence of query history, while [LocalWorkspaceStorageProvider.java](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/chat2db-community-storage/src/main/java/ai/chat2db/community/storage/LocalWorkspaceStorageProvider.java) manages workspace state using a local file-based implementation.

Can I run Chat2DB without the desktop GUI?

Yes. By setting -Dchat2db.gui=false when starting the JVM, the backend runs in headless mode, exposing only the REST API on the configured port (default 10825). This allows deployment as a standalone server or integration into CI/CD pipelines for automated database operations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}