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

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 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 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
• 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 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:

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:

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:

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 and implement the required Dialect interfaces. Register the module in the parent 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:

@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.

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.

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. 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.

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