# robocup-ssl-china/rocos architecture

> Architecture diagram of the GitHub repository robocup-ssl-china/rocos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/robocup-ssl-china/rocos
- Repository: https://github.com/robocup-ssl-china/rocos

## Overview

##### Main Components
- Client Module:
– Contains GUI elements (Qt/QML files), resource files, and simulation plugins.
- Controller Module:
– Provides interfaces for user input and remote control via gamepads or other devices.
– This module uses QML for control widgets and integrates libraries to process serial and radio communication.
- Core Module:
– Acts as the computational heart of the framework.
– It is divided into many subcomponents including:
▪ Algorithm (ball/robot tracking, collision checking)
▪ MotionControl (dynamics, control models, equations solvers)
▪ PathPlan (trajectory planning and obstacle avoidance)
▪ Vision (vision processing, ball and robot prediction, collision simulation)
▪ WorldModel (maintaining game state, referee information, and robot capabilities)
▪ Simulator and RefereeBox for interfacing with external simulation and referee systems
▪ LuaModule for extensibility and scripting skills.
- Shared/Support Libraries:
– The “share” directory and “cmake” modules include communication protocols (protobuf definitions) and geometric utilities.
– These components are key for integrating various modules and ensuring smooth data flow.
- ZBin and Related Scripts:
– This houses logs, binaries, test scripts, parameters, and additional utilities for running, debugging, and tweaking the overall system.
- External Integrations:
– Integration with continuous integration workflows (.github sub-folders), Sphinx/doc configuration, and third-party libraries (found in “OtherLibs” and “tactics”) are evidence of the system’s integrated development workflow and simulation of game tactics.

##### Relationships and Interactions
- The Client (frontend) displays simulation data, sends user commands to the Core, and receives visualization output from core processing modules.
- The Controller gathers and converts real-time user inputs (from a gamepad or other controllers) and passes those inputs to the Core – via defined communication protocols (potentially over serial or network interfaces).
- The Core module processes inputs from both the Client and Controller:
– The Algorithm subcomponent computes real-time ball and robot states.
– MotionControl and PathPlan generate movement trajectories and commands which are then possibly fed to the wireless module to control actual robots.
– Vision captures visual data, runs prediction and tracking, and then updates the world model.
– The RefereeBox and Simulator modules ensure that decisions conform to game rules and simulate tactical strategies.
- Shared libraries ensure consistency in data formats (e.g., protobuf-based messages) across all these modules.

##### Architectural Patterns and Technologies
- Layered/MVC Approach:
– The separation of GUI (Client), control input (Controller), and business logic (Core) suggests a separation akin to Model-View-Controller, where the Core acts as the Model, the Client serves as the View, and the Controller module provides the input mechanism.
- Plug-in Architecture:
– The “Client/plugins” directory (and even within Core’s Lua modules) shows that functionality can be extended or changed by swapping modules (e.g., different physics objects and tactics).
- Use of CMake:
– Centralized build configuration via CMakeLists.txt files across many directories suggests a modular build that compiles these individual components and integrates them.
- Scripting Integration:
– Lua scripting files under Core/tactics and in ZBin/lua_scripts indicate that many high-level decisions and behaviors are configured through script files, making the system adaptable.
- Communication Protocols:

– Data/instruction flow from Controller and Client to Core.
– Feedback flow (e.g., simulation results, log updates, display data) from Core back to Client.
– Inter-component dependencies such as offline analysis, Lua scripting interactions, and shared utilities.
- Annotations to call out key architectural design patterns (e.g., plugin extensibility in Lua modules, modular build with CMake, communication via Protocol Buffers).

## Diagram (Mermaid)

```mermaid
flowchart TB

    %% Client Layer
    subgraph "Client Layer (UI and Simulation)"
        A["Client (UI and Simulation)"]:::ui
    end

    %% Controller Layer
    subgraph "Controller Layer (Input Handling)"
        B["Controller (Input Handling)"]:::controller
    end

    %% Core Module with Submodules
    subgraph "Core Module (Business Logic)"
        C["Core (Central Processing)"]:::core
        subgraph "Core Submodules"
            D["Algorithm (Tracking & Collision)"]:::core
            E["MotionControl (Dynamics & Control)"]:::core
            F["PathPlan (Trajectory Planning)"]:::core
            G["Vision (Image Processing)"]:::core
            H["WorldModel (Game State)"]:::core
            I["RefereeBox (Game Rules)"]:::core
            J["Simulator (Simulation Interface)"]:::core
            K["LuaModule (Scripting)"]:::core
        end
    end

    %% Shared Libraries and Protocols
    subgraph "Shared Libraries & Protocols"
        L["Shared Libraries (Proto & Utilities)"]:::shared
    end

    %% Auxiliary Tools and Scripts
    subgraph "Auxiliary Tools and Scripts"
        M["ZBin (Logs, Binaries, Scripts)"]:::aux
    end

    %% External Integrations (CI, Docs, Third-party)
    subgraph "External Integrations"
        N["External Integrations (CI, Docs, Third-party)"]:::external
    end

    %% Data Flow Connections
    A -->|"visualCommands"| C
    B -->|"controlInputs"| C
    C -->|"simulationResults"| A

    %% Core Submodules Interactions
    D -->|"tracking-informed"| E
    E -->|"controlCommands"| F
    G -->|"updateState"| H
    I -->|"rulesInfo"| H
    F -->|"simulateMove"| J
    K -->|"scripting"| C
    J -->|"viewFeedback"| A

    %% Integration with Shared Libraries
    C -->|"uses"| L
    B -->|"protocols"| L
    L -->|"integrationData"| N

    %% Additional Interactions with Auxiliary and External Tools
    C -->|"logs/debug"| M
    C -->|"integration"| N

    %% Class Definitions for styling
    classDef ui fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef controller fill:#ABEBC6,stroke:#196F3D,stroke-width:2px;
    classDef core fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef shared fill:#F5CBA7,stroke:#D35400,stroke-width:2px;
    classDef aux fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
    classDef external fill:#FAD7A0,stroke:#CA6F1E,stroke-width:2px;

    %% Click Events for Component Mapping
    click A "https://github.com/robocup-ssl-china/rocos/tree/main/Client/"
    click B "https://github.com/robocup-ssl-china/rocos/tree/main/Controller/"
    click C "https://github.com/robocup-ssl-china/rocos/tree/main/Core/"
    click D "https://github.com/robocup-ssl-china/rocos/tree/main/Core/src/Algorithm"
    click E "https://github.com/robocup-ssl-china/rocos/tree/main/Core/src/MotionControl"
    click F "https://github.com/robocup-ssl-china/rocos/tree/main/Core/src/PathPlan"
    click G "https://github.com/robocup-ssl-china/rocos/tree/main/Core/src/Vision"
    click H "https://github.com/robocup-ssl-china/rocos/tree/main/Core/src/WorldModel"
    click I "https://github.com/robocup-ssl-china/rocos/tree/main/Core/src/RefereeBox"
    click J "https://github.com/robocup-ssl-china/rocos/tree/main/Core/src/Simulator"
    click K "https://github.com/robocup-ssl-china/rocos/tree/main/Core/src/LuaModule"
    click L "https://github.com/robocup-ssl-china/rocos/tree/main/share/"
    click M "https://github.com/robocup-ssl-china/rocos/tree/main/ZBin/"
    click N "https://github.com/robocup-ssl-china/rocos/tree/main/.github/"
```
