CLAUDE

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is the bytedesk.wiki repository, the official wiki for the Bytedesk enterprise customer service and collaboration platform. It provides structured documentation for developers, operators, and maintainers working with the main Bytedesk project.

Note: This wiki repository complements the main Bytedesk codebase repository. This wiki focuses on development workflows, deployment procedures, and architectural guidance.

Tech Stack

Backend (Main Codebase)

• Java 21
• Spring Boot 3.5.x
• Maven multi-module architecture
• Databases: MySQL / PostgreSQL / Oracle / KingbaseES
• Message Queues: Artemis / RabbitMQ

Frontend (Main Codebase)

• Node.js >= 20.19.0 or >= 22.12.0
• pnpm 10
• Turborepo monorepo
• Multiple applications: admin backend, agent client, visitor portal

Infrastructure

• Redis
• Elasticsearch
• MinIO
• Optional: Ollama (AI), ASR/TTS, Janus, Coturn, FreeSWITCH

Project Structure (Main Codebase Monorepo)

bytedesk/
├── modules/          # Core business modules (IM, service, kbase, ticket, ai, voc, etc.)
├── starter/          # Runtime entrypoints and aggregation
├── channels/         # External channel integrations
├── plugins/          # Optional plugins (FreeSWITCH, WebRTC, open platform)
├── enterprise/       # Enterprise edition capabilities
├── control/          # Control plane/admin backend
├── projects/         # Custom projects and extensions
├── frontend/         # pnpm + Turborepo frontend workspace
├── deploy/           # Docker, K8s, Nginx, SQL deployment assets
├── docs/             # Docusaurus documentation site
├── mobile/           # Mobile-related code
├── apidocs/          # API documentation output
└── scripts/          # Automation scripts

Core Business Modules

• team: Enterprise IM, organization structure, roles & permissions
• service: Online customer service, routing, agent workspace
• kbase: Knowledge base, help center, FAQ
• ticket: Ticket system and SLA
• ai: Model integration, RAG, function calling, MCP
• voc: Voice of customer, feedback, surveys
• social: Social IM
• call: Call center basic capabilities
• webrtc: WebRTC audio/video basic capabilities

Deployment Scenarios

Bytedesk uses a scenario-based deployment model:

• standard: Standard customer service & collaboration
• noai: Simplified without AI dependencies
• call: With call center capabilities
• webrtc: With WebRTC audio/video customer service
• call-webrtc: Both voice and audio/video capabilities enabled

Common Development Commands

Docker Middleware (Local Development)

cd deploy/docker
cp .env.example .env
./start.sh mysql artemis standard middleware  # Start infrastructure only
./stop.sh mysql artemis standard down middleware

Frontend Development

cd frontend
nvm use
pnpm install
pnpm dev          # Start dev server
pnpm build        # Production build
pnpm lint         # Code linting
turbo dev --filter=web  # Run specific app only

Documentation Site

cd docs
pnpm install
pnpm build
pnpm start-cn     # Start Chinese docs site

Full Deployment

cd deploy/docker
./start.sh mysql artemis standard all  # Start middleware + app

start.sh Parameter Model

./start.sh <db> <mq> <scenario> <target>

• db: mysql | postgresql | oracle | kingbase9
• mq: artemis | rabbitmq
• scenario: standard | noai | call | webrtc | call-webrtc
• target: middleware | all

Recommended Development Workflow

1. Use Docker to run middleware (database, MQ, Redis, ES)
2. Run backend services from source in IDE
3. Run frontend dev server from frontend workspace

Troubleshooting Principles

1. First revert to the baseline combination: mysql + artemis + standard
2. Remove optional factors like call, webrtc, AI
3. Confirm whether the issue is in backend, frontend, or deployment layer

Important Notes

• docs vs wiki: docs/ is for the official documentation site, this wiki is for repository collaboration and maintenance
• Module Location: Business capabilities are primarily in modules/, optional extensions in plugins/
• Environment Variables: All sensitive variables should go in .env, never commit to repository
• Default Passwords: Always replace default passwords before production deployment

Key Files in This Wiki

• Home - Main entry point and project overview
• 快速开始 (Quick Start) - 5-minute onboarding
• 开发指南 (Development Guide) - Backend, frontend, docs setup
• 部署指南 (Deployment Guide) - Docker, K8s, production deployment
• 项目结构 (Project Structure) - Monorepo layout explanation
• 模块地图 (Module Map) - Business modules and extension points
• 架构概览 (Architecture Overview) - Runtime layers and technical stack