# Main Directories in the Chat2DB Repository: A Complete Developer Guide

> Explore the main directories in the Chat2DB repository including React frontend, Spring Boot backend, Docker, and more. Understand the structure with this developer guide.

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

---

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

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

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

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

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

- [[`chat2db-community-client/.umirc.desktop.ts`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-client/.umirc.desktop.ts)](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-client/.umirc.desktop.ts) — Configures the desktop (JCEF) mode of the UI.
- [[`chat2db-community-server/pom.xml`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/pom.xml)](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/pom.xml) — Maven parent POM that declares all backend modules and dependencies.
- [`docker/Dockerfile`](https://github.com/OtterMind/Chat2DB/blob/main/docker/Dockerfile) — Defines the backend service container image.
- [[`script/package/package-community-jcef.sh`](https://github.com/OtterMind/Chat2DB/blob/main/script/package/package-community-jcef.sh)](https://github.com/OtterMind/Chat2DB/blob/main/script/package/package-community-jcef.sh) — Orchestrates native packaging for the desktop client.
- [[`spec/code/server/java-module-boundaries.md`](https://github.com/OtterMind/Chat2DB/blob/main/spec/code/server/java-module-boundaries.md)](https://github.com/OtterMind/Chat2DB/blob/main/spec/code/server/java-module-boundaries.md) — Describes the allowed dependency graph between server modules.
- [[`docs/guides/bigquery.md`](https://github.com/OtterMind/Chat2DB/blob/main/docs/guides/bigquery.md)](https://github.com/OtterMind/Chat2DB/blob/main/docs/guides/bigquery.md) — Example user-facing guide stored under `docs/`.
- [[`.github/workflows/ci.yml`](https://github.com/OtterMind/Chat2DB/blob/main/.github/workflows/ci.yml)](https://github.com/OtterMind/Chat2DB/blob/main/.github/workflows/ci.yml) — CI pipeline that builds, tests, and validates the repository.

## 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)](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.