# Architecture Overview

Bytedesk is a multi-module business platform with multi-scenario deployment capabilities and multi-client frontends. Understand the architecture from three dimensions: runtime components, engineering organization, and scenario extensions.

## Runtime Architecture

### Access Layer
- **Frontend Applications** - Admin dashboard, agent workbench, visitor portal, desktop app
- **External Channels** - WeChat, Douyin, web, mobile, and third-party integrations
- **Open Platform APIs** - RESTful APIs and SDKs for custom integrations

### Application Layer
- **Team IM** - Enterprise messaging and collaboration
- **Customer Service** - Multi-channel support and routing
- **Knowledge Base** - Documentation and RAG system
- **Ticket System** - Issue tracking and workflow
- **AI Agent** - LLM integration and function calling
- **VOC** - Voice of customer feedback
- **Call Center** - Voice call management
- **WebRTC** - Video call and screen sharing

### Infrastructure Layer
- **Databases** - MySQL, PostgreSQL, Oracle, KingbaseES
- **Message Queues** - Artemis (default), RabbitMQ
- **Caching** - Redis
- **Search** - Elasticsearch
- **Object Storage** - MinIO
- **AI Services** - Ollama (local), ZhipuAI, DeepSeek
- **Voice/Video** - FreeSWITCH, Janus, Coturn

## Engineering Architecture

### Backend Organization
- **Maven Multi-module** - Root project aggregates backend modules
- **Module Separation** - Business modules in `modules/`, plugins in `plugins/`
- **Configuration** - Centralized in `starter/src/main/resources/`

### Frontend Organization
- **Turborepo Monorepo** - pnpm workspace with multiple apps
- **Shared Packages** - Common components and utilities
- **Build System** - Vite for fast development and builds

### Deployment Organization
- **Docker Compose** - Scenario-based deployment files
- **Environment Variables** - Centralized in `.env`
- **Infrastructure as Code** - All deployment assets in repo

## Scenario Extension Model

Bytedesk supports multiple deployment scenarios, not just a single "standard" version:

| Scenario | Description | Use Case |
|----------|-------------|----------|
| `standard` | Standard customer service with AI | Default deployment |
| `noai` | Without AI dependencies | Simplified deployments |
| `call` | With call center (FreeSWITCH) | Voice support needs |
| `webrtc` | With WebRTC video | Video support needs |
| `call-webrtc` | Both voice and video | Full-featured support |

### Key Points about Scenarios
- **Development/Testing** - Confirm which scenario you're working with
- **Production Deployment** - Start with minimal viable scenario, add capabilities later
- **Dependencies** - Some scenarios require additional infrastructure (FreeSWITCH, Janus, Coturn)

## Architecture Understanding Guide

### Business Perspective
1. Identify which business capability you need
2. Locate the corresponding module in `modules/`
3. Check if there are related plugins or channels
4. Understand the data flow and dependencies

### System Perspective
1. Determine if the change is in frontend, backend, or deployment
2. Locate the correct directory in the monorepo
3. Understand the module boundaries and dependencies
4. Test changes in the appropriate scenario

### Deployment Perspective
1. Select database and message queue first
2. Choose the appropriate scenario
3. Configure environment variables in `.env`
4. Monitor logs and component health

## Architecture Review Considerations

When reviewing or modifying the architecture, consider:
- Which capabilities are in the default baseline vs optional plugins
- Which dependencies are interchangeable (database, MQ)
- Which scenarios introduce additional operational complexity (call, webrtc, AI)
- Clear separation between `docs/` (official site) and this wiki (repo collaboration)

## Technology Stack Details

### Backend Stack
- **Java 21** - Language
- **Spring Boot 3.5.x** - Framework
- **Spring Data JPA** - ORM
- **Spring Security** - Security
- **WebSocket** - Real-time communication
- **Spring AI** - AI integration
- **Flowable** - Workflow engine
- **QueryDSL** - Type-safe queries

### Frontend Stack
- **TypeScript** - Language
- **React** - UI framework
- **Ant Design** - Component library
- **Zustand** - State management
- **Vite** - Build tool
- **Turborepo** - Monorepo build system

### Mobile Stack
- **Flutter** - Cross-platform framework
- **Dart** - Language
- **UniApp** - Lightweight mobile framework

### DevOps Stack
- **Docker** - Containerization
- **Docker Compose** - Orchestration
- **Kubernetes** - Container orchestration (optional)
- **Nginx** - Reverse proxy
- **Elastic Stack** - Logging and monitoring