# Module Structure of chat2db-community-server: Maven Multi-Module Architecture Guide

> Explore the Maven multi-module architecture of chat2db-community-server. Discover its nine specialized modules and clean architecture principles for flexible database integration.

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

---

**The `chat2db-community-server` is a Maven multi-module project comprising nine specialized modules—including BOM, domain, storage, start, web, JCEF, plugins, SPI, and tools—that enforces clean architecture principles through API/implementation separation and runtime-pluggable database dialects.**

The `chat2db-community-server` module serves as the back-end foundation for the Chat2DB Community edition, housed within the [OtterMind/Chat2DB](https://github.com/OtterMind/Chat2DB) monorepo. Understanding the module structure of `chat2db-community-server` is essential for contributors who need to extend database support, modify business logic, or integrate custom persistence layers.

## Overview of the Nine Core Modules

The top-level [`chat2db-community-server/pom.xml`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/pom.xml) aggregates nine child modules that inherit common configuration for Java 17, Lombok, MapStruct, and Maven compiler plugins. This structure ensures consistent dependency management while maintaining strict separation of concerns between the web layer, business logic, and database-specific implementations.

The nine modules defined in the parent POM are:

- `chat2db-community-bom` – Centralizes version catalogs for the entire server side
- `chat2db-community-domain` – Core business entities and services
- `chat2db-community-storage` – MyBatis-based persistence layer
- `chat2db-community-start` – Spring Boot bootstrap and executable assembly
- `chat2db-community-tools` – Command-line utilities for schema generation
- `chat2db-community-web` – REST controllers and HTTP endpoints
- `chat2db-community-jcef` – Java Chromium Embedded Framework integration for desktop clients
- `chat2db-community-plugins` – Database dialect implementations (MySQL, PostgreSQL, Oracle, etc.)
- `chat2db-community-spi` – Service Provider Interface defining extension contracts

## Domain and Persistence Architecture

### chat2db-community-domain: API and Implementation Separation

The domain module follows a hexagonal architecture pattern by splitting into two sub-modules:

- **`chat2db-community-domain-api`** – Contains public interfaces and DTOs that other modules depend on, located at [`chat2db-community-domain/chat2db-community-domain-api/pom.xml`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-domain/chat2db-community-domain-api/pom.xml)
- **`chat2db-community-domain-core`** – Houses the actual service implementations, transaction boundaries, and business rules

This separation ensures that the web layer and plugins depend only on abstractions, not concrete implementations, preventing circular dependencies and enabling testing with mock implementations.

### chat2db-community-storage: Data Access Layer

The storage module provides MyBatis mapper files and repository implementations that the domain layer uses to persist entities. It abstracts database-specific SQL generation, allowing the domain layer to remain agnostic to whether the underlying store is MySQL, PostgreSQL, or H2.

## Application Bootstrap and Web Layer

### chat2db-community-start: Spring Boot Entry Point

The start module contains the executable Spring Boot application. The `Application` class at [`chat2db-community-start/src/main/java/ai/chat2db/community/start/Application.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-start/src/main/java/ai/chat2db/community/start/Application.java) serves as the runtime entry point, responsible for component scanning, configuration loading, and automatic discovery of plugin JARs.

### chat2db-community-web: REST Controllers

This module exposes HTTP endpoints consumed by the Chat2DB frontend. Controllers in this module depend only on the `chat2db-community-domain-api` interfaces, maintaining clean architectural boundaries between transport and business logic.

## Extensibility Through SPI and Plugins

### chat2db-community-spi: Extension Contracts

The SPI module defines interfaces that database-specific implementations must satisfy, including connection management, metadata extraction, and dialect-specific SQL generation. This module contains no implementation—only contracts that plugins must fulfill.

### chat2db-community-plugins: Database Dialects

Each supported database lives as its own Maven submodule under `chat2db-community-plugins/`. Examples include:

- `chat2db-community-mysql`
- `chat2db-community-postgresql`
- `chat2db-community-sqlite`
- `chat2db-community-bigquery`

These modules implement the SPI interfaces and are discovered at runtime via Spring's `@ComponentScan`. The plugin architecture allows adding new database support without modifying core domain code.

## Building and Running the Server

### Compiling the Entire Project

To compile all modules and package the executable JAR, execute the following from the repository root:

```bash
mvn -B -f chat2db-community-server/pom.xml clean package -DskipTests

```

This command generates the executable artifact at `chat2db-community-start/target/chat2db-community.jar` alongside individual plugin JARs.

### Starting the Community Server

Run the assembled application with specific runtime flags to enable community mode:

```bash
java -Dchat2db.runtime.mode=community \
     -Dchat2db.network.status=OFFLINE \
     -jar chat2db-community-server/chat2db-community-start/target/chat2db-community.jar

```

The `Application` class boots the Spring context, initializes the embedded servlet container, and loads all discovered plugins from the classpath.

## Implementing Custom Database Plugins

To extend Chat2DB with a custom database dialect, create a new Maven module under `chat2db-community-plugins`:

```bash
mvn archetype:generate \
    -DgroupId=ai.chat2db \
    -DartifactId=chatdb-community-mydb \
    -DarchetypeArtifactId=maven-archetype-quickstart \
    -DinteractiveMode=false \
    -f chatdb-community-server/chatdb-community-plugins/pom.xml

```

Add a dependency on `chat2db-community-spi` in the new module's [`pom.xml`](https://github.com/OtterMind/Chat2DB/blob/main/pom.xml) and implement the required `Dialect` interfaces. Register the module in the parent [`pom.xml`](https://github.com/OtterMind/Chat2DB/blob/main/pom.xml) under `<modules>` to include it in the build lifecycle.

### Accessing Plugins Programmatically

Services in the domain layer consume plugins through the SPI abstraction. For example, obtaining a datasource connection through the MySQL plugin:

```java
@Autowired
private DataSourceService dataSourceService;   // Defined in domain SPI

DataSource ds = dataSourceService.getDataSource("mysql", jdbcUrl, user, pwd);
Connection conn = ds.getConnection();          // Delegates to chat2db-community-mysql

```

The `DataSourceService` implementation resolves the appropriate plugin based on the identifier string, as configured in [`chat2db-community-plugins/chat2db-community-mysql/pom.xml`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-plugins/chat2db-community-mysql/pom.xml).

## Summary

- **Nine-module Maven architecture** groups the Chat2DB Community back-end into distinct BOM, domain, storage, start, web, JCEF, tools, SPI, and plugins components.
- **Clean dependency direction** ensures web and storage layers depend only on domain APIs, not implementations.
- **Plugin system** uses the SPI module to support runtime database dialect discovery without core code changes.
- **Spring Boot bootstrap** in the start module auto-wires all components and launches the embedded server.
- **Standardized build** inherits Java 17, Lombok, and MapStruct configuration from the parent [`chat2db-community-server/pom.xml`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/pom.xml).

## Frequently Asked Questions

### What is the purpose of the chat2db-community-bom module?

The `chat2db-community-bom` (Bill of Materials) centralizes version numbers for all third-party dependencies used across the nine server modules. By importing this BOM in child POMs, the project ensures consistent dependency versions and simplifies version upgrades by changing a single property in the parent POM.

### How does the domain layer maintain independence from database implementations?

The domain layer splits into `chat2db-community-domain-api` and `chat2db-community-domain-core` sub-modules. Other modules depend only on the API module, which contains interfaces and DTOs, while the core module houses implementations. This prevents the web layer and plugins from coupling to specific business logic implementations.

### Where is the Spring Boot application entry point located?

The executable entry point resides in [`chat2db-community-start/src/main/java/ai/chat2db/community/start/Application.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-start/src/main/java/ai/chat2db/community/start/Application.java). This class contains the `main` method that launches the Spring context, loads configuration files, and performs component scanning to discover controllers, services, and database plugins automatically.

### How are new database dialects added to the system?

New dialects are added as Maven submodules under `chat2db-community-plugins/`, implementing interfaces defined in `chat2db-community-spi`. After implementing the required contracts (such as connection management and SQL generation), the module is registered in the parent POM's `<modules>` section. The start module discovers these implementations at runtime through Spring's classpath scanning.