# soniccloudorg/sonic-server architecture

> Architecture diagram of the GitHub repository soniccloudorg/sonic-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/soniccloudorg/sonic-server
- Repository: https://github.com/soniccloudorg/sonic-server

## Overview

The project is a multi-module backend platform called “Sonic Cloud Real Machine Platform”. Its purpose is to integrate remote control debugging with automated mobile device testing – essentially providing both device control and testing orchestration capabilities. The source tree reveals that it is organized as a Maven multi-module project with the following key modules:

1. sonic-server-common – a shared library providing common configuration, exception handling, HTTP response models, and various utility tools.
2. sonic-server-controller – the core service module responsible for exposing REST endpoints (via many controller classes), handling business logic, data mapping via MyBatis, and scheduling operations (note presence of Quartz jobs). It also contains modules for transport (TransportServer/Worker) that may handle communication with remote devices.
3. sonic-server-eureka – a service registry and discovery module (typical Eureka server) that handles microservices registration.
4. sonic-server-folder – a dedicated module for file and folder management. It even comes with Docker support.
5. sonic-server-gateway – an API gateway module that provides a unified entry point to the services. It manages requests via filters (AuthFilter, CORSConfig, etc.) for security and routing to backend controllers.

A. Identify Main Components:
- API Gateway (sonic-server-gateway): Acts as the entry point for client requests. It applies filtering (authentication, CORS) and routes traffic appropriately.
- Service Registry (sonic-server-eureka): Manages service discovery and registration among the microservices.
- Core Controller Service (sonic-server-controller): Contains a rich set of REST controllers to handle device operations, test case management, job scheduling, and real-time communications. Also includes sub-components like transport servers/workers and integration with persistent storage (MyBatis mappers, Quartz for scheduled jobs).
- Shared Library (sonic-server-common): Provides centralized functionality used by other modules (error handling, JWT tools, I18n configuration, common exceptions, etc.).
- File Management Service (sonic-server-folder): Handles file uploads and directory management tasks specifically related to folders.
- (Optionally) Infrastructure components such as databases, Docker deployments (noted by docker-compose files and Dockerfiles), and external integrations with client devices.

B. Determine Relationships and Interactions:
- The controller service interacts with the common module to enforce validation/error handling and share common config.
- The service registry (Eureka) enables dynamic service discovery between the gateway and the various microservices.
- Within the controller module, REST controllers call service layer implementations which then interact with the persistence layer (MyBatis mappers) to manage data (and may trigger Quartz jobs for scheduled tasks).
- The transport components in the controller module facilitate two-way communication with mobile devices (robots, debug clients).

C. Highlight Architectural Patterns and Technologies:
- Microservices Architecture: Separation of concerns is clear by dividing the system into distinct modules (gateway, controller, folder, eureka, and common). Each module serves a specific responsibility.
- API Gateway Pattern: The sonic-server-gateway acts as the front-door to the microservices system.
- Service Discovery: The use of a Eureka server (sonic-server-eureka) for service registration and discovery.
- Shared Library Usage: The common module promotes code reuse by centralizing configuration, error handling, and utility functions.
- Use of Docker: Presence of Dockerfiles and docker-compose YAML files implies containerization for deployment.
- Technologies: Spring Boot (inferred from the package structure and configuration files), MyBatis for ORM, Quartz for scheduling tasks, and Spring Cloud components (Eureka, Gateway, Feign clients) for inter-service communication.

- For this backend platform (a full-stack system where the “frontend” is likely either separately maintained or integrated as client apps), clearly show the flow from external clients to the API Gateway, then service discovery by Eureka before reaching the backend microservices.
- Separation between the modules (controller, folder, eureka, and gateway) and show how the shared common module supports the other services.
- Internal sub-components within the controller module:
- The REST controllers
- The service layer (including implementations for handling business logic, job processing via Quartz, and transport communication)
- The persistence layer (via MyBatis mappers).
- External dependencies such as the database and any remote device connections that are central to remote control debugging and automated testing.

- From Clients → Gateway → Service Registry (Eureka) → Appropriate Microservice (Controller/Folder).
- Internal calls from Controller’s REST API to service layer and persistence.
- Component with its key responsibilities and any specific technologies (e.g., “Spring Boot”, “MyBatis”, “Quartz”, “Docker”).

1. A high-level overview placing external clients at the top.
4. Branch out to the core microservices: “sonic-server-controller” and “sonic-server-folder”. Under the controller module, subdivide further into:
- REST controllers (e.g., AgentsController, DevicesController, etc.)
- Service layer (with Quartz job schedulers and business logic)
- Data access layer (MyBatis mappers)
- Transport sub-system (TransportServer and TransportWorker)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Clients("External Clients"):::client

    %% API Gateway
    Gateway("API Gateway"):::gateway

    %% Service Registry
    Eureka("Service Registry"):::registry

    %% Shared Library
    Common("Shared Library"):::common

    %% File Management Service
    Folder("File Management Service"):::folder

    %% Core Controller Service Subgraph
    subgraph "Core Controller Service"
        RestCtrl("REST Controllers"):::controller
        SvcLayer("Service Layer Interface"):::controller
        SvcImpl("Service Layer Implementation"):::controller
        Persistence("Persistence Layer (MyBatis)"):::internal
        Scheduling("Scheduling (Quartz)"):::internal
        Transport("Transport Components"):::internal
    end

    %% Connections from External Clients
    Clients -->|"API_Call"| Gateway

    %% API Gateway and Service Registry Interaction (Bi-directional)
    Gateway <-->|"Service_Discovery"| Eureka

    %% API Gateway routes to Microservices
    Gateway -->|"API_Call"| RestCtrl
    Gateway -->|"API_Call"| Folder

    %% Shared Library Dependency
    Gateway -->|"DependsOn"| Common
    Eureka -->|"DependsOn"| Common
    RestCtrl -->|"DependsOn"| Common
    Folder -->|"DependsOn"| Common

    %% Internal Controller Module Flow
    RestCtrl -->|"Calls"| SvcLayer
    SvcLayer -->|"Delegates"| SvcImpl
    SvcImpl -->|"CRUD_Operations"| Persistence
    SvcImpl -->|"Schedules"| Scheduling
    SvcImpl -->|"Transports"| Transport

    %% Click Events
    click Gateway "https://github.com/soniccloudorg/sonic-server/tree/main/sonic-server-gateway/src/main/java/org/cloud/sonic/gateway"
    click Eureka "https://github.com/soniccloudorg/sonic-server/tree/main/sonic-server-eureka/src/main/java/org/cloud/sonic/eureka"
    click RestCtrl "https://github.com/soniccloudorg/sonic-server/tree/main/sonic-server-controller/src/main/java/org/cloud/sonic/controller/controller"
    click SvcLayer "https://github.com/soniccloudorg/sonic-server/tree/main/sonic-server-controller/src/main/java/org/cloud/sonic/controller/services"
    click SvcImpl "https://github.com/soniccloudorg/sonic-server/tree/main/sonic-server-controller/src/main/java/org/cloud/sonic/controller/services/impl"
    click Persistence "https://github.com/soniccloudorg/sonic-server/tree/main/sonic-server-controller/src/main/java/org/cloud/sonic/controller/mapper"
    click Scheduling "https://github.com/soniccloudorg/sonic-server/tree/main/sonic-server-controller/src/main/java/org/cloud/sonic/controller/quartz"
    click Transport "https://github.com/soniccloudorg/sonic-server/tree/main/sonic-server-controller/src/main/java/org/cloud/sonic/controller/transport"
    click Common "https://github.com/soniccloudorg/sonic-server/tree/main/sonic-server-common/src/main/java/org/cloud/sonic/common"
    click Folder "https://github.com/soniccloudorg/sonic-server/tree/main/sonic-server-folder/src/main/java/org/cloud/sonic/folder"

    %% Styles
    classDef client fill:#90EE90,stroke:#008000,stroke-width:2px;
    classDef gateway fill:#EDF2F7,stroke:#2C7A7B,stroke-width:2px;
    classDef registry fill:#F0E68C,stroke:#B8860B,stroke-width:2px;
    classDef controller fill:#FFCCCB,stroke:#FF6347,stroke-width:2px;
    classDef internal fill:#F5DEB3,stroke:#D2691E,stroke-width:2px;
    classDef common fill:#D3D3D3,stroke:#808080,stroke-width:2px;
    classDef folder fill:#E6E6FA,stroke:#8A2BE2,stroke-width:2px;
```
