Project Structure

Project Structure

Bytedesk uses a Monorepo architecture with backend, frontend, deployment assets, and documentation in a single repository.

Top-Level Overview

bytedesk/
├── channels/          # External channel integrations
├── control/           # Control plane and admin services
├── modules/           # Core business modules
├── plugins/           # Optional plugins and extensions
├── projects/          # Custom projects and special integrations
├── enterprise/        # Enterprise edition features
├── starter/           # Application entry points
├── frontend/          # pnpm + Turborepo frontend workspace
├── mobile/            # Mobile applications (Flutter, UniApp)
├── deploy/            # Deployment assets (Docker, K8s, Nginx)
├── docs/              # Docusaurus documentation site
├── apidocs/           # API documentation output
├── scripts/           # Automation scripts and utilities
└── images/            # Documentation images and screenshots

Directory Responsibilities

Core Backend Directories

modules/ - Core Business Modules

This is where most product capabilities live:

• team/ - Team IM, organization, roles, permissions
• service/ - Customer service, routing, agent workbench
• kbase/ - Knowledge base, help center, FAQ
• ticket/ - Ticket management and SLA
• ai/ - AI agent, models, RAG, function calling
• voc/ - Voice of customer, feedback, surveys
• social/ - Social IM features
• call/ - Call center basic capabilities
• webrtc/ - WebRTC video capabilities
• core/ - Shared utilities and infrastructure
• forum/ - Forum functionality
• bi/ - Business intelligence and reporting
• training/ - Training and onboarding
• disk/ - File storage and management
• meet/ - Meeting and conferencing
• remote/ - Remote support capabilities
• opinion/ - Feedback and review management

starter/ - Application Entry Point

• Main Spring Boot application: StarterApplication.java
• Aggregates all modules for runtime
• Configuration files: application*.properties

channels/ - External Integrations

Connect external platforms and channels:

• wechat/ - WeChat integration
• douyin/ - Douyin/TikTok integration
• shop/ - E-commerce platform integrations
• social/ - Social media platform integrations

plugins/ - Optional Plugins

Enhancement features that can be optionally enabled:

• freeswitch/ - FreeSWITCH call center integration
• webrtc/ - WebRTC video and audio support
• openplatform/ - Open API and developer platform

enterprise/ - Enterprise Edition

Enhanced enterprise features:

• core/, ai/, kbase/, service/, ticket/, call/ - Enterprise-licensed versions

control/ & projects/

• control/ - Control plane and admin services
• projects/ - Custom implementations and special integrations

Frontend & Client Directories

frontend/ - Web Applications

Monorepo managed with pnpm and Turborepo:

• apps/ - Individual frontend applications
  • admin/ - Admin dashboard
  • agent/ - Agent workbench
  • visitor/ - Visitor chat widget
  • desktop/ - Desktop application
  • chat/ - Chat application
  • datav/ - Data visualization
  • meet/ - Meeting application
  • remote/ - Remote support
  • training/ - Training platform
• packages/ - Shared libraries and components

mobile/ - Mobile Applications

• flutter/ - Flutter cross-platform apps
• uniapp/ - UniApp lightweight mobile apps

Deployment & Documentation

deploy/ - Deployment Assets

• docker/ - Docker Compose configurations
  • Multiple compose files for different scenarios
  • start.sh and stop.sh scripts
• kubernetes/ - Kubernetes deployment files
• nginx/ - Nginx configuration
• sql/ - Database initialization scripts
• server/ - Server configuration and scripts

docs/ - Documentation Site

• Docusaurus-based documentation
• Multi-language support
• Build and deployment scripts

Module Organization Principles

The project is organized to emphasize:

• Business modularity - Each module represents a business capability
• Pluggable extensions - Optional features are in plugins/
• Deployment with code - Deployment assets live with the codebase

New Contributor Recommendations

1. Don't try to read everything - Focus on your area first
2. Start with modules/ - Most development happens here
3. Check frontend/ for UI development
4. Refer to deploy/ for deployment changes
5. Use Module Map to understand business capabilities

Dependency Notes

• All modules depend on modules/core
• starter/ aggregates all modules for runtime
• Channel and plugin modules are optional
• Enterprise modules require licensing