Skip to content

CLAUDE

Jump to bottom
jack ning edited this page Jun 15, 2026 · 2 revisions

CLAUDE.md

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

Wiki Overview

This is the official wiki for the Bytedesk project, which is an AI-powered omnichannel customer service platform with team cooperation capabilities.

Important: This wiki repository complements the main Bytedesk codebase repository at /Users/ningjinpeng/Desktop/Git/Github/private/bytedesk-2x/. This wiki focuses on documentation for developers, operators, and maintainers.

Project Overview

What is Bytedesk?

Bytedesk is a comprehensive platform providing:

  • Team IM - Enterprise instant messaging with organizational structure
  • Customer Service - Multi-channel customer support and routing
  • Knowledge Base - RAG-enabled documentation and FAQ system
  • Ticket System - Issue tracking with SLA management
  • AI Agent - LLM integration with function calling
  • Call Center - Voice call support via FreeSWITCH
  • Video Customer Service - WebRTC-based video calls
  • Open Platform - RESTful APIs and multi-language SDKs

Technology Stack

Backend

  • Java 21 - Programming language
  • Spring Boot 3.5.x - Web framework
  • Maven - Build and dependency management
  • Databases: MySQL, PostgreSQL, Oracle, KingbaseES
  • Message Queues: Artemis (default), RabbitMQ
  • Caching: Redis
  • Search: Elasticsearch
  • AI Integration: Spring AI, Ollama, ZhipuAI, DeepSeek

Frontend

  • Node.js 20+ - Runtime
  • pnpm 10 - Package manager
  • Turborepo - Monorepo build system
  • React - UI framework
  • TypeScript - Language
  • Ant Design - Component library
  • Zustand - State management
  • Vite - Build tool

Mobile

  • Flutter - Cross-platform framework
  • Dart - Language
  • UniApp - Lightweight mobile framework

DevOps

  • Docker & Docker Compose - Containerization
  • Kubernetes - Orchestration (optional)
  • Nginx - Reverse proxy
  • Elastic Stack - Logging and monitoring

Main Project Structure

The Bytedesk main repository uses a monorepo architecture:

bytedesk/
├── modules/          # Core business modules
│   ├── team/         # Team IM & organization
│   ├── service/      # Customer service
│   ├── kbase/        # Knowledge base
│   ├── ticket/       # Ticket system
│   ├── ai/           # AI agent
│   ├── voc/          # Voice of customer
│   ├── call/         # Call center
│   ├── webrtc/       # WebRTC video
│   ├── core/         # Core infrastructure
│   └── ...           # Other modules
├── plugins/          # Optional plugins
│   ├── freeswitch/   # FreeSWITCH integration
│   ├── webrtc/       # WebRTC integration
│   └── openplatform/ # Open API platform
├── channels/         # External channel integrations
│   ├── wechat/       # WeChat integration
│   ├── douyin/       # Douyin integration
│   ├── shop/         # E-commerce integrations
│   └── social/       # Social integrations
├── starter/          # Application entry point
├── frontend/         # Frontend workspace
│   ├── apps/         # Individual applications
│   │   ├── admin/    # Admin dashboard
│   │   ├── agent/    # Agent workbench
│   │   ├── visitor/  # Visitor widget
│   │   └── ...       # Other apps
│   └── packages/     # Shared libraries
├── deploy/           # Deployment assets
│   └── docker/       # Docker Compose files
├── enterprise/       # Enterprise features
├── control/          # Control plane
├── projects/         # Custom projects
├── mobile/           # Mobile applications
├── docs/             # Docusaurus documentation site
└── scripts/          # Automation scripts

Scenario Deployment Model

Bytedesk supports multiple deployment scenarios:

Scenario Description
standard Standard customer service with AI capabilities
noai Without AI dependencies, simpler deployment
call With call center capabilities (FreeSWITCH)
webrtc With WebRTC video capabilities
call-webrtc Both call center and WebRTC video

Common Development Commands

Docker Deployment

cd deploy/docker
cp .env.example .env

# Start middleware only (for development)
./start.sh mysql artemis standard middleware

# Start full stack (for testing/production)
./start.sh mysql artemis standard all

# Stop containers
./stop.sh mysql artemis standard stop middleware

# Remove containers (keep volumes)
./stop.sh mysql artemis standard down middleware

Backend Development

# Build entire project
mvn clean install

# Build without tests
mvn clean install -DskipTests

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

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

Frontend Development

cd frontend
nvm use
pnpm install

# Start all apps
pnpm dev

# Start specific app
turbo dev --filter=admin

# Build all apps
pnpm build

# Lint
pnpm lint

Documentation Development

cd docs
pnpm install
pnpm build
pnpm start-cn

Docker Start/Stop Script Parameters

# Start script
./start.sh <db> <mq> <scenario> <target>

# Stop script
./stop.sh <db> <mq> <scenario> <action> <target>

Parameters:

  • db: mysql, postgresql, oracle, kingbase9
  • mq: artemis, rabbitmq
  • scenario: standard, noai, call, webrtc, call-webrtc
  • target: middleware, all
  • action: stop, down

Important Notes for This Wiki

File Naming Convention

  • Use English filenames with spaces replaced by hyphens (e.g., Quick-Start.md)
  • All content should be in English
  • Keep the sidebar (_Sidebar.md) updated when adding new pages

Wiki Maintenance Principles

  • Focus on "how to start, locate, and decide" - Don't repeat what's already in the code
  • Document default paths, recommended combinations, and common scenarios - Reduce onboarding friction
  • Update this wiki first when commands, module boundaries, or dependency matrices change

Important Distinctions

  • docs/ - Official documentation site (Docusaurus), for end users
  • This wiki - Repository collaboration, maintenance, and development documentation, for contributors

Default Access

Key Files in This Wiki

Links to Main Project

  • Main Repository: /Users/ningjinpeng/Desktop/Git/Github/private/bytedesk-2x/
  • Main README: /Users/ningjinpeng/Desktop/Git/Github/private/bytedesk-2x/README.md
  • Main CLAUDE.md: /Users/ningjinpeng/Desktop/Git/Github/private/bytedesk-2x/CLAUDE.md
  • Docker README: /Users/ningjinpeng/Desktop/Git/Github/private/bytedesk-2x/deploy/docker/readme.md

License

Copyright (c) 2013-2025 微语 Bytedesk.com, All rights reserved.

Licensed under GNU AFFERO GENERAL PUBLIC LICENSE (AGPL v3).

Bytedesk Wiki

Getting Started

Core Documentation

Development & Deployment

External Links

Clone this wiki locally