# How to Contribute to the Chat2DB Project: Complete Developer Guide

> Learn how to contribute to the Chat2DB project. Follow our developer guide to fork the repo, set up your environment, build the backend and frontend, and submit your pull request.

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

---

**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`](https://github.com/OtterMind/Chat2DB/blob/main/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`](https://github.com/OtterMind/Chat2DB/blob/main/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`](https://github.com/OtterMind/Chat2DB/blob/main/docker-build.sh) and native installer scripts.
- **Documentation** — `docs/`, [`README.md`](https://github.com/OtterMind/Chat2DB/blob/main/README.md), and [`CONTRIBUTING.md`](https://github.com/OtterMind/Chat2DB/blob/main/CONTRIBUTING.md) supply user guides and contribution rules.

### Backend Module Boundaries

Per [`spec/code/server/java-module-boundaries.md`](https://github.com/OtterMind/Chat2DB/blob/main/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`](https://github.com/OtterMind/Chat2DB/blob/main/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:

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

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

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

```

Launch the backend JAR with the community runtime profile:

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

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

```bash
yarn run lint
yarn run test

```

## Contribution Workflow

Clone your fork locally:

```bash
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`](https://github.com/OtterMind/Chat2DB/blob/main/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:

```java
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`](https://github.com/OtterMind/Chat2DB/blob/main/src/test/java/ai/chat2db/service/MyNewServiceTest.java):

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

```tsx
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`](https://github.com/OtterMind/Chat2DB/blob/main/src/config/routes.ts):

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

```

### Build a Docker Image

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

```bash
./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`](https://github.com/OtterMind/Chat2DB/blob/main/./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`](https://github.com/OtterMind/Chat2DB/blob/main/spec/code/server/java-module-boundaries.md) and the PR template in [`CONTRIBUTING.md`](https://github.com/OtterMind/Chat2DB/blob/main/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`](https://github.com/OtterMind/Chat2DB/blob/main/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`](https://github.com/OtterMind/Chat2DB/blob/main/./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.