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

> Explore the modular Spring Boot backend architecture of Chat2DB. Discover its distinct layers from bootstrap to database plugins for efficient operation.

- Repository: [OtterMind/Chat2DB](https://github.com/OtterMind/Chat2DB)
- Tags: architecture
- Published: 2026-07-27

---

**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/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/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/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/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`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/chat2db-community-storage/src/main/java/ai/chat2db/community/storage/small/SmallDataStorage.java) – Handles lightweight metadata.
- [`LargeDataStorage`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/chat2db-community-storage/src/main/java/ai/chat2db/community/storage/large/LargeDataStorage.java) – Manages large result sets and binary cells.
- [[`LocalWorkspaceStorageProvider.java`](https://github.com/OtterMind/Chat2DB/blob/main/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/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/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/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/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`](https://github.com/OtterMind/Chat2DB/blob/main/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:

```bash
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:

```bash
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:

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

```

Then implement the plugin entry point:

```java
@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/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/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.