# Project Structure

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

## Top-Level Overview

```text
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