Development Guide

Development Guide

Set up your development environment for backend, frontend, and documentation.

Prerequisites

Backend Development

• JDK 21 - Java Development Kit
• Maven - Build tool
• Docker & Docker Compose - For running middleware
• IDE - IntelliJ IDEA, Eclipse, or VS Code

Frontend Development

• Node.js - Version 20.19.0+ or 22.12.0+
• pnpm 10 - Package manager
• nvm (optional) - Node Version Manager
• IDE - VS Code, WebStorm, etc.

Documentation Development

• Node.js - For Docusaurus
• pnpm - Package manager

Recommended Development Mode

We recommend **Docker for infrastructure + source for business applications:

1. Start middleware via Docker Compose
2. Run backend from source in your IDE
3. Run frontend from source with hot reload

This approach provides:

• Environment parity with production
• Clear boundaries between components
• Flexible single-module debugging
• Fast hot reload for frontend changes

Backend Development

Project Setup

# Clone the repository
git clone https://github.com/Bytedesk/bytedesk.git
cd bytedesk

# Start middleware first
cd deploy/docker
cp .env.example .env
./start.sh mysql artemis standard middleware

# Return to project root and build
cd ../..
mvn clean install -DskipTests

IDE Setup

1. Import the root pom.xml into your IDE
2. Configure JDK 21 as the project SDK
3. Wait for Maven dependencies to download
4. Locate StarterApplication.java in starter/src/main/java/com/bytedesk/starter/
5. Run it as a Java application or Spring Boot app

Maven Commands

# Build entire project
mvn clean install

# Build without running tests
mvn clean install -DskipTests

# Build specific module
mvn clean install -pl modules/service

# Run tests
mvn test

# Run specific test module
mvn test -pl modules/service

# Run single test class
mvn test -Dtest=YourTestClass

# Run single test method
mvn test -Dtest=YourTestClass#testMethod

# Generate Javadoc
mvn javadoc:javadoc

# Run the application from starter module
cd starter
mvn spring-boot:run

Backend Modules

The root pom.xml aggregates:

• channels/ - External channel integrations
• control/ - Control plane and admin services
• modules/ - Core business modules
• plugins/ - Optional plugins
• projects/ - Custom projects
• enterprise/ - Enterprise features
• starter/ - Application entry point

Configuration Files

• Main Configuration: starter/src/main/resources/application*.properties
• Profiles:
  • application.properties - Default profile
  • application-dev.properties - Development profile
  • application-prod.properties - Production profile

Frontend Development

Workspace Setup

cd frontend

# Use correct Node version
nvm use

# Install dependencies
pnpm install

Development Commands

# Start all apps in development mode
pnpm dev

# Start specific app
turbo dev --filter=admin
turbo dev --filter=agent
turbo dev --filter=visitor
turbo dev --filter=desktop

# Build all apps
pnpm build

# Build specific app
turbo build --filter=admin

# Lint all code
pnpm lint

# Format code
pnpm format

# Run tests
pnpm test

Frontend Structure

frontend/
├── apps/          # Individual applications
│   ├── admin/     # Admin dashboard
│   ├── agent/     # Agent workbench
│   ├── visitor/   # Visitor chat widget
│   ├── desktop/   # Desktop app
│   └── ...
└── packages/      # Shared libraries

Documentation Site Development

The docs/ directory contains the official documentation site built with Docusaurus.

Documentation Setup

cd docs
pnpm install

Documentation Commands

# Build documentation
pnpm build

# Start Chinese documentation site
pnpm start-cn

# Start English documentation site
pnpm start-en

Recommended Development Workflow

Feature Development

1. Locate the relevant module(s) in the Module Map
2. Start the minimal required middleware
3. Develop backend changes in the appropriate module
4. Develop frontend changes in the appropriate app
5. Test end-to-end with both backend and frontend running

Troubleshooting Workflow

1. Return to baseline: mysql + artemis + standard
2. Remove optional scenarios: no call, webrtc, or ai dependencies
3. Isolate whether the issue is in backend, frontend, or deployment
4. Check logs and configuration

Before You Commit

Code Quality Checks

• Did you modify the correct module(s)?
• Are backend and frontend configurations in sync?
• Do deployment or documentation need updates?
• Are local-only configuration changes excluded from commit?
• Did you run tests for the modules you modified?
• Is sensitive information kept out of code and commits?

Git Guidelines

• Keep commits focused and atomic
• Write clear commit messages
• Don't commit secrets or passwords
• Don't commit large binary files
• Keep .env files out of version control

Debugging Tips

Backend Debugging

• Set breakpoints in your IDE
• Check logs in starter/logs/
• Use Elasticsearch/Kibana for log aggregation
• Monitor database queries
• Check message queue health

Frontend Debugging

• Use browser dev tools
• Check network requests
• Use React DevTools
• Check console for errors
• Verify WebSocket connections

Docker Debugging

# Check running containers
docker compose -p bytedesk ps

# View logs
docker compose -p bytedesk logs -f

# View specific service logs
docker compose -p bytedesk logs -f bytedesk-mysql

# Enter a container
docker exec -it bytedesk-mysql bash

# Restart a service
docker compose -p bytedesk restart bytedesk-redis

Environment Setup Tips

• Use dev profile for development - application-dev.properties
• Never commit real secrets - Keep them in .env or local config
• Use middleware mode for local development - Faster and more reliable
• Consider using Docker for full integration testing
• Refer to Deployment Guide for production setup