getting-started

Main Directories in the Chat2DB Repository: A Complete Developer Guide

July 27, 2026 OtterMind/Chat2DB ↗

The Chat2DB repository is organized into eight top-level directories—chat2db-community-client/, chat2db-community-server/, docker/, script/, jpackage/, spec/, docs/, and .github/—that separate the React frontend, Spring Boot backend, containerization, packaging, specifications, documentation, and CI workflows.

Chat2DB is an open-source, community-edition database client maintained by OtterMind. Understanding the main directories in the Chat2DB repository is essential for contributors who need to navigate the codebase, build the application locally, or extend its plugin system. The top-level layout reflects a modular, multi-language architecture that cleanly isolates the Java backend, TypeScript frontend, Docker deployments, and native packaging resources.

Overview of the Main Directories in the Chat2DB Repository

The repository root contains eight primary directories. Each one maps to a distinct layer of the application lifecycle, from user-interface code to installer generation.

chat2db-community-client: React and Umi Frontend

The chat2db-community-client/ directory houses the entire user interface. It is a React application built with Umi, Ant Design, and Zustand for state management. This folder also contains the JCEF bridge that renders the web UI inside the desktop client, making it critical for both the web and desktop distributions.

Representative source: chat2db-community-client/src

chat2db-community-server: Spring Boot Backend

The chat2db-community-server/ directory contains the Spring Boot backend written in Java 17. It defines domain services, data-source management, the plugin system, REST controllers, and the JCEF-native launcher. The Maven parent POM inside this directory orchestrates all server-side modules.

Representative source: [chat2db-community-server/pom.xml](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/pom.xml)

docker: Containerized Deployment

The docker/ folder provides the Dockerfile and compose scripts needed to build and run the backend in containers. The UI is served separately, so this directory targets containerized deployment of the server component only.

Representative source: docker/Dockerfile

script: Packaging and CI Orchestration

The script/ directory stores helper scripts for packaging, continuous integration, encryption-key handling, and desktop-packaging utilities. These scripts tie together the build steps that produce release artifacts.

Representative source: [script/package/package-community-jcef.sh](https://github.com/OtterMind/Chat2DB/blob/main/script/package/package-community-jcef.sh)

jpackage: Native Installer Resources

The jpackage/ directory holds resources consumed by the native-packaging step. This includes platform-specific assets—such as jpackage/input/macres/Info.plist—that jpackage uses to produce Windows, macOS, and Linux installers.

spec: Formal Contracts and Boundaries

The spec/ directory contains formal contract documentation that defines module boundaries, API contracts, and plugin interfaces. Developers use these specifications to keep the codebase consistent and to enforce allowed dependency graphs between server modules.

Representative source: [spec/code/server/java-module-boundaries.md](https://github.com/OtterMind/Chat2DB/blob/main/spec/code/server/java-module-boundaries.md)

docs: End-User Documentation

The docs/ folder contains human-readable guides, tutorials, and integration docs for end users. Topics range from BigQuery setup to AI-assistant configuration.

Representative source: [docs/guides/bigquery.md](https://github.com/OtterMind/Chat2DB/blob/main/docs/guides/bigquery.md)

.github: CI Workflows and Templates

The .github/ directory stores GitHub Actions workflows, issue templates, and contribution policies. It drives the automated pipelines that build both frontend and backend, run tests, and validate pull requests.

Representative source: [.github/workflows/ci.yml](https://github.com/OtterMind/Chat2DB/blob/main/.github/workflows/ci.yml)

Build and Runtime Workflow by Directory

The following commands illustrate how each main directory contributes to everyday development.

Compile and Run the Backend

From the repository root, move into the server directory and use Maven to build the community start module:

cd chat2db-community-server
mvn -B clean package \
  -Dmaven.test.skip=true \
  -Dchat2db.finalName=chat2db-community \
  -pl chat2db-community-start -am
java -Dchat2db.runtime.mode=community \
     -Dchat2db.network.status=OFFLINE \
     -Dserver.port=10825 \
     -jar chat2db-community-start/target/chat2db-community.jar

Start the Frontend Locally

The client directory uses Yarn to install dependencies and produce a development build:

cd chat2db-community-client
yarn install --frozen-lockfile
yarn run lint
yarn run build:web:community --app_version=0.0.0

Build a Docker Image for the Backend

Use the docker directory to containerize the server:

cd docker
./docker-build.sh 0.0.0-local chat2db-community:local
docker compose up -d

The container exposes the backend on 127.0.0.1:10825.

Create a Native Linux Installer

The script and jpackage directories work together to produce native installers:

cd script/package
./package-linux_community.sh 0.0.0-local

This script wraps jpackage with the resources located under jpackage/input.

Key Entry Points in the Chat2DB Repository Directories

Several files act as practical entry points that reveal the purpose of each main directory:

Summary

  • The main directories in the Chat2DB repository are chat2db-community-client/, chat2db-community-server/, docker/, script/, jpackage/, spec/, docs/, and .github/.
  • chat2db-community-client/ provides the React and Umi frontend, including the JCEF bridge for desktop rendering.
  • chat2db-community-server/ hosts the Java 17 Spring Boot backend with its Maven module structure.
  • docker/ supplies container definitions for backend-only deployment.
  • script/ and jpackage/ automate CI tasks and native installer generation across platforms.
  • spec/, docs/, and .github/ maintain code contracts, user guides, and automated workflows.

Frequently Asked Questions

What is the purpose of the chat2db-community-client directory?

The chat2db-community-client/ directory contains the React and Umi frontend for Chat2DB. It manages UI components, state with Zustand, and the JCEF bridge that renders the web interface inside the native desktop application.

How is the Chat2DB backend organized?

The backend lives in chat2db-community-server/ and is implemented in Java 17 with Spring Boot. It is structured as a Maven multi-module project that handles domain services, data-source management, REST controllers, and the JCEF-native launcher.

Can I deploy Chat2DB using Docker?

Yes. The docker/ directory provides a Dockerfile and compose scripts for containerized deployment. The Docker image typically contains only the backend service, while the frontend is served separately.

Where are the API contracts and module boundaries documented?

Formal contracts are stored in the spec/ directory. The file [spec/code/server/java-module-boundaries.md](https://github.com/OtterMind/Chat2DB/blob/main/spec/code/server/java-module-boundaries.md) explicitly defines the allowed dependency graph and plugin interfaces between server modules.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →