How to Contribute to the Chat2DB Project: Complete Developer Guide

To contribute to the Chat2DB project, fork the OtterMind/Chat2DB repository, install Java 17 and Node 18, build the Spring Boot backend with Maven, start the Umi frontend with Yarn, and open a pull request against the main branch following CONTRIBUTING.md.

Chat2DB is an open-source, multi-database client maintained by OtterMind that pairs a Java 17 Spring Boot backend with a TypeScript/React Umi frontend. Learning how to contribute to the Chat2DB project requires understanding its Maven module layout and cross-platform build pipeline. By placing code in the correct directory and respecting the module boundaries, you can extend backend services, add frontend pages, or package new Docker releases.

Architecture Overview

The repository is organized into distinct layers according to the OtterMind/Chat2DB source code.

• Backend Core — chat2db-community-server/chat2db-community-start hosts the Spring Boot entry point, Chat2DbApplication.java, and manages runtime mode selection.
• Backend Modules — Multiple Maven modules under chat2db-community-server/* provide domain services, storage APIs, plugin SPI, and web controllers.
• Database Plugins — chat2db-community-server/chat2db-community-plugins contains dialect-specific drivers for MySQL, PostgreSQL, ClickHouse, and others.
• Frontend Client — chat2db-community-client is a Umi-based React SPA that handles state management, UI components, and the JCEF bridge for desktop builds.
• Packaging & Docker — docker/ and script/package/ hold docker-build.sh and native installer scripts.
• Documentation — docs/, README.md, and CONTRIBUTING.md supply user guides and contribution rules.

Backend Module Boundaries

Per spec/code/server/java-module-boundaries.md, controllers must stay thin, business logic belongs in domain services, and persistence is accessed through SPI interfaces. Frontend code follows standard Umi conventions documented in chat2db-community-client/readme.md: pages live under src/pages and services under src/services. Adhering to these boundaries keeps your changes compatible with both the Community and commercial editions.

Development Environment Setup

Prerequisites

Before building, install the following tools:

• Java 17
• Maven 3.8+
• Node.js 18+
• Yarn (the repository includes a yarn.lock)

Build the Spring Boot Backend

Compile the community starter and its dependencies:

mvn -B clean package -Dmaven.test.skip=true \
   -Dchat2db.finalName=chat2db-community \
   -f chat2db-community-server/pom.xml \
   -pl chat2db-community-start -am

Install and Start the Frontend

cd chat2db-community-client
yarn install --frozen-lockfile
yarn run start:community:hot

Run Chat2DB Locally

Before starting the server, generate the AES-256-GCM encryption key required for password storage:

./script/security/init-community-encryption-key.sh

Launch the backend JAR with the community runtime profile:

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

Open http://localhost:10825 in a browser to verify the UI loads.

Testing Your Changes

Backend Module Tests

The project disables the default Maven test runner. To run tests for a specific module, use:

MODULE=:chat2db-community-spi
TEST=DefaultSqlBuilderSegmentTest
mvn -B -f chat2db-community-server/pom.xml \
    -pl "${MODULE}" -am \
    -Dmaven.test.skip=false -DskipTests=false \
    -Dtest="${TEST}" \
    -Dsurefire.failIfNoSpecifiedTests=false \
    -Dmaven.test.failure.ignore=false test

Frontend Lint and Unit Tests

yarn run lint
yarn run test

Contribution Workflow

Clone your fork locally:

git clone https://github.com/<your-username>/Chat2DB.git
cd Chat2DB

Then follow these steps to submit your work:

1. Create a feature branch from main.
2. Commit your changes with clear messages.
3. Open a pull request against the upstream main branch using the template in CONTRIBUTING.md.
4. Link related issues with Fixes #<issue-number> so they close automatically on merge.

Common Contribution Examples

These examples illustrate how to contribute to the Chat2DB project across the backend, frontend, and packaging layers.

Add a New Backend Service

Create the service class in the appropriate module:

package ai.chat2db.service;

import org.springframework.stereotype.Service;

@Service
public class MyNewService {
    public String hello(String name) {
        return "Hello, " + name + "!";
    }
}

Spring Boot auto-registers the bean via component scanning. Add a unit test under src/test/java/ai/chat2db/service/MyNewServiceTest.java:

package ai.chat2db.service;

import static org.junit.jupiter.api.Assertions.*;
import org.junit.jupiter.api.Test;

class MyNewServiceTest {
    @Test
    void greeting() {
        MyNewService svc = new MyNewService();
        assertEquals("Hello, Alice!", svc.hello("Alice"));
    }
}

Extend the Frontend UI

Add a new page in the chat2db-community-client package:

import React from 'react';
import { Card } from 'antd';

export default function Welcome() {
  return (
    <Card title="Welcome to Chat2DB">
      <p>Start by adding a datasource from the left menu.</p>
    </Card>
  );
}

Then register the route in src/config/routes.ts:

{
  path: '/dashboard/welcome',
  component: '@/pages/dashboard/Welcome',
}

Build a Docker Image

Use the official script to create an image and start the stack:

./docker/docker-build.sh 5.3.0 chat2db/chat2db:5.3.0
docker compose -f docker/docker-compose.yml up --detach

Summary

• Fork the OtterMind/Chat2DB repository and branch from main.
• Install Java 17, Maven 3.8+, Node 18+, and Yarn before compiling.
• Build the backend with Maven targeting the chat2db-community-start module.
• Generate the encryption key with ./script/security/init-community-encryption-key.sh before running the server locally.
• Follow the module boundaries defined in spec/code/server/java-module-boundaries.md and the PR template in CONTRIBUTING.md.

Frequently Asked Questions

Which branch should I target when contributing to Chat2DB?

Submit all pull requests against the upstream main branch. The project requires that you use the PR template referenced in CONTRIBUTING.md and link related issues using Fixes #<issue-number> for automatic closure.

How do I run tests for a specific backend module?

Run Maven with the module path and test class name explicitly set. For example, set MODULE=:chat2db-community-spi and TEST=DefaultSqlBuilderSegmentTest, then invoke mvn -B -f chat2db-community-server/pom.xml -pl "${MODULE}" -am test with test skipping disabled.

What encryption setup is required before running the application locally?

You must execute ./script/security/init-community-encryption-key.sh before launching the JAR. This script generates the AES-256-GCM key that the Spring Boot backend uses to encrypt stored passwords in community mode.

Where are database-specific drivers implemented in Chat2DB?

Dialect-specific drivers reside in chat2db-community-server/chat2db-community-plugins. Each database, such as MySQL or ClickHouse, has its own subdirectory that implements the plugin SPI.

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