crmdesk/AGENTS.md

AGENTS.md

This file provides guidance to AI coding agents (Codex, GitHub Copilot, etc.) when working with code in this repository.

Project Overview

Bytedesk is an AI-powered omnichannel customer service platform with team cooperation capabilities, providing enterprise instant messaging, customer service, knowledge base, ticket management, and AI agent functionality.

This repository is backend-only: a Java 21 + Spring Boot 4.1.0 multi-module Maven monorepo. Frontend applications live in separate repositories (see frontend/readme.md):

• Web (visitor widget + admin): https://github.com/Bytedesk/bytedesk-web
• Desktop (Electron): https://github.com/Bytedesk/bytedesk-desktop
• Mobile: https://github.com/Bytedesk/bytedesk-mobile

Architecture

Backend Architecture (Java 21 + Spring Boot 4.1.0)

• Entry Point: starter/src/main/java/com/bytedesk/starter/StarterApplication.java
• Core Stack: Spring Boot 4.1.0, Spring Data JPA, Spring Security (OAuth2/OIDC + LDAP), WebFlux alongside Spring MVC; Jetty servlet container (Tomcat excluded)
• Concurrency: Java 21 virtual threads enabled (spring.threads.virtual.enabled=true)
• Messaging: Netty-based WebSocket/MQTT/STOMP stack in modules/core/src/main/java/com/bytedesk/core/socket/ (HTTP port 9003, WebSocket port 9885); broker selected via bytedesk.mq.type (default artemis; rabbitmq/kafka/rocketmq also supported)
• Database: MySQL (primary), Redis (caching + message queuing), H2 (testing); PostgreSQL/Oracle/KingBase also supported, selected via bytedesk.datasource.active
• Migrations: Liquibase, master change log at starter/src/main/resources/db/changelog/master.xml
• Workflow Engines: Flowable 8.0.0 (ticket workflows), COLA state machine 5.0.0 (core workflows; Spring StateMachine 4.0.0 also on the classpath during migration to COLA)
• AI: Spring AI 2.0.0 based integration with 20+ providers, MCP client/server, and Agent Skills (see AI Integration below)
• Multi-module Maven structure; root aggregator modules: channels, modules, plugins, starter

Module Structure

Root Maven modules (pom.xml): channels, modules, plugins, starter

• channels/ - Aggregator only; all channel modules (wechat, whatsapp, email, dingtalk, ...) are currently commented out in channels/pom.xml
• plugins/ - Optional plugins; only kanban is active (appoint, backup, calendar, elearning, note, pdf, socialhub, form are commented out)
• starter/ - Spring Boot application aggregating the active modules

Backend Modules (modules/):

• core/ - Core functionality and utilities (protobuf/gRPC codegen, WebSocket/MQTT/STOMP stack, COLA state machine, RBAC, quartz, push, workflow)
• team/ - Team IM and organizational structure
• service/ - Customer service and routing
• kbase/ - Knowledge base management
• ai/ - AI integration (Spring AI 2.0.0): 20+ LLM providers (anthropic, azure, baidu, bedrock, custom, dashscope, deepseek, dmr, gitee, google, groq, huggingface, minimax, mistralai, moonshot, nvidia, ollama, openai, openrouter, perplexity, siliconflow, tencent, volcengine, zhipuai), robot/robot_thread, MCP client & server, agent skills, tool/tool_call/tool_audit, RAG
• ticket/ - Ticket management, SLA, Flowable 8 workflows
• call/ - Call center functionality (FreeSWITCH)
• meet/ - Meeting/conferencing
• webrtc/ - WebRTC video support
• voc/ - Voice of customer feedback
• forum/ - Forum functionality
• social/ - Social features
• bi/ - Business intelligence (built, but currently NOT aggregated into starter)
• crm/ - CRM functionality
• disk/ - File storage
• mall/ - Mall/e-commerce
• marketing/ - Marketing tools
• opinion/ - Opinion/feedback
• remote/ - Remote support
• training/ - Training management
• cli/ - Command line interface

Note: modules/shop/ contains only stale build output (target/) and is NOT a module in modules/pom.xml; do not use it.

Plugins (plugins/):

• kanban/ - Kanban board functionality (built, but NOT aggregated into starter)

Development Commands

Backend (Maven)

Prefer the repository wrapper (./starter/mvnw) instead of assuming a global Maven; JDK 21 is required.

# Build entire project
./starter/mvnw -f pom.xml clean install -DskipTests

# Build a specific module (with its dependencies)
./starter/mvnw -f pom.xml -pl modules/core -am -DskipTests install

# Run application (default profile: noai; JASYPT_ENCRYPTOR_PASSWORD optional, see Environment Pitfalls)
./starter/mvnw -f starter/pom.xml spring-boot:run

# Generate Javadoc
./starter/mvnw javadoc:javadoc

Docker Deployment

cd deploy/docker

# Usage: ./start.sh <db> <mq> <scenario> <target> [observability]
#   db: mysql | postgresql | oracle | kingbase9 (aliases: pg, kingbase)
#   mq: artemis | rabbitmq
#   scenario: standard | noai | call | webrtc | call-webrtc
#   target: all | middleware
#   observability (5th arg): obs | observability | true

# Start without AI (default active profile of the app is also noai)
./start.sh mysql artemis noai all

# Standard scenario
./start.sh mysql artemis standard all

# Only middleware (DB/MQ/etc.), no app container
./start.sh mysql artemis standard middleware

# With observability stack (Prometheus/Grafana)
./start.sh mysql artemis standard all obs

Notes:

• call and call-webrtc scenarios only support mysql/postgresql backends
• Compose assets: compose-base.yaml, compose-db-*.yaml, compose-mq-{artemis,rabbitmq}.yaml, compose-scenario-{standard,noai,call,webrtc}.yaml, compose-app-*.yaml, compose-observability.yaml
• deploy/docker/one/ contains all-in-one compose files for quick single-node deployment
• stop.sh for teardown, watchdog.sh for monitoring

Key Technologies and Patterns

Backend Patterns

• JPA Entities: Domain models with Spring Data JPA repositories
• REST Controllers: Spring MVC controllers with OpenAPI/Swagger (springdoc) documentation
• WebSocket Controllers: Real-time messaging via Netty
• Service Layer: Business logic in service classes
• Security: Spring Security with OAuth2/OIDC + LDAP support; optional Jasypt property encryption for ENC(...) values
• Workflows: Flowable 8 (ticket processes), COLA state machine (core workflows)
• Caching: Redis + Caffeine (local cache)
• Message Queue: bytedesk.mq.type selects the broker (default artemis; rabbitmq/kafka/rocketmq supported); ActiveMQ Artemis / RabbitMQ available via Docker compose; embedded Artemis server dependency included
• Templates: FreeMarker is primary; Thymeleaf restricted to error/*, excel/*, file/* views

Plugin Patterns

• Plugins: Optional capabilities layered on modules/; only kanban currently active and it is NOT aggregated into starter
• Channels: All channel modules are disabled (commented out in channels/pom.xml); re-enable by un-commenting the desired module

Important Notes

Database Support

The database is selected via bytedesk.datasource.active (default mysql):

• MySQL (primary production)
• PostgreSQL
• H2 (development/testing)
• Oracle
• KingBase

Datasource files: starter/src/main/resources/properties/<profile>/datasource/50-datasource-*.properties (common + per-DB).

Default login: admin@email.com / admin

AI Integration

Built on Spring AI 2.0.0 with 20+ providers under modules/ai/.../providers/: Ollama (local), ZhipuAI (default provider of the open profile), DeepSeek, DashScope, OpenAI, Anthropic, Azure, Google, Bedrock, Moonshot, Minimax, SiliconFlow, Volcengine, Tencent, Baidu, Gitee, Groq, Mistral AI, NVIDIA, Perplexity, OpenRouter, HuggingFace, DMR, plus a custom provider.

• The open profile sets ZhipuAI as default for chat/embedding/vision/audio/rerank/multimodal models (properties/open/70-ai-batch-liquibase.properties)
• Elasticsearch vector store (custom VectorStoreConfig); Spring AI JDBC ChatMemory tables managed by Liquibase (spring.ai.chat.memory.repository.jdbc.initialize-schema=never)
• MCP (properties/<profile>/75-mcp.properties): MCP client and server are disabled by default (spring.ai.mcp.client.enabled=false, spring.ai.mcp.server.enabled=false); when enabled, bearer-token auth applies and only read-only tools are exposed by default
• Agent Skills (properties/<profile>/76-skills.properties): shell / filesystem / web-fetch skill tools; disabled in the noai profile, enabled in open; skill definitions live under starter/src/main/resources/skills/

Module Dependencies

• All modules depend on modules/core
• Starter aggregates: core, team, service, kbase, ai, crm, marketing, ticket, call, meet, webrtc, voc, forum, social, remote, training, cli
• Not currently aggregated into starter: bi (commented out in starter/pom.xml), disk, mall, opinion, and the kanban plugin
• All channel modules are disabled (commented out in channels/pom.xml)

Configuration Files

• Main: starter/src/main/resources/application.properties — sets spring.profiles.active=noai by default
• Profiles: noai (default, AI disabled) and open (AI enabled, ZhipuAI default). application-noai.properties / application-open.properties import modular configs from starter/src/main/resources/properties/{noai,open}/
• Modular configs are numbered for ordering: 30-core-business, 31-call-freeswitch, 32-webrtc, 33-cache-redis, 40-oauth-ldap, 41-logging, 51-jpa-web-actuator, 60-mq-mail-quartz, 70-ai-batch-liquibase, 75-mcp, 76-skills, 80-flowable, 90-thirdparty-cloud, 99-docker-compose, plus datasource/50-*
• Docker: deploy/docker/compose-*.yaml

Environment Pitfalls

• Default local HTTP port is 9003, WebSocket port is 9885; check port conflicts before concluding startup failure
• Local dev commonly requires MySQL + Redis (Docker compose in deploy/docker/ is the usual path); Spring Boot docker-compose lifecycle is disabled (spring.docker.compose.enabled=false) — use deploy/docker/start.sh / stop.sh instead
• JASYPT_ENCRYPTOR_PASSWORD is only required if you actually use ENC(...) encrypted properties; shipped configs contain only commented examples, so startup works without it
• bytedesk.licenseKey may need a trial license for some features (see comments in application-noai.properties)
• modules/core includes protobuf/gRPC generation (CI installs protoc 23.x); if related classes are missing, rebuild core with -pl modules/core -am
• Liquibase migrations live under starter/src/main/resources/db/changelog/; do not introduce Flyway
• Prefer minimal scoped changes; do not refactor unrelated modules in the same task

Testing

Backend Tests

# Run all tests
./starter/mvnw -f pom.xml test

# Run tests for specific module
./starter/mvnw -f pom.xml -pl modules/core test

# Run single test class
./starter/mvnw test -Dtest=YourTestClass

# Run single test method
./starter/mvnw test -Dtest=YourTestClass#testMethod

Build Artifacts

• Main JAR: starter/target/bytedesk-starter.jar (finalName fixed in starter/pom.xml)
• Generated Javadocs: starter/src/main/resources/static/javadocs/
• Swagger/OpenAPI: Available at /swagger-ui.html when running
• Docker image: built from starter/Dockerfile (eclipse-temurin:21-jdk base), published to jackning/bytedesk on Docker Hub

CI/CD

• .github/workflows/bytedesk.yml: triggered on v* tag pushes; JDK 21 (temurin) + protoc 23.x, Maven build, creates GitHub release
• .github/modernize/: modernization workflow assets

Development Workflow

1. Backend Development: Work in specific modules under modules/, test via starter app
2. Plugins: Add optional capabilities in plugins/ (only kanban active)
3. Channels: Currently disabled; re-enable by un-commenting modules in channels/pom.xml
4. Full Stack Testing: Run backend on port 9003; frontends (separate repos) connect via REST/WebSocket (9885)
5. Docker Testing: Use deploy/docker/start.sh for full environment testing

License

Business Source License 1.1 - Can be used for commercial purposes but prohibits resale, SaaS hosting, or deployment for illegal businesses without permission.