# 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

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

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

```bash
cd frontend

# Use correct Node version
nvm use

# Install dependencies
pnpm install
```

### Development Commands

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

```bash
cd docs
pnpm install
```

### Documentation Commands

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