# alliander-opensource/rcdt_robotics architecture

> Architecture diagram of the GitHub repository alliander-opensource/rcdt_robotics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alliander-opensource/rcdt_robotics
- Repository: https://github.com/alliander-opensource/rcdt_robotics

## Overview

##### Project Type and Purpose
- This is a robotics framework and toolkit (“RCDT Robotics”) built around ROS 2. It provides:
- A set of ROS 2 packages for robot control (Franka, Panther, mobile manipulators)
- Perception (rcdt_detection) and action orchestration (rcdt_actions)
- Simulation support via Gazebo (rcdt_gazebo)
- Utilities (rcdt_utilities, rcdt_sensors, rcdt_messages)
- A Python-based workflow/orchestration engine (pyflow)
- Docker/devcontainer setup for reproducible development and CI

##### Key Architectural Areas (based on file structure)
- Dev Environment & CI
- .devcontainer, Dockerfiles, .github/workflows
- Local_run, get_image_tag, scripts in dockerfiles/install_scripts
- Documentation
- docs/ with Sphinx configuration, content folders, images/videos
- Workflow Engine
- pyflow/ (default_config, graphs, packages/RCDT)
- ROS 2 Workspace
- ros2_ws/src containing ~12 ROS 2 packages:
– rcdt_messages (action/srv definitions)
– rcdt_actions (action servers/clients)
– rcdt_detection (vision pipelines)
– rcdt_franka (+MoveIt config)
– rcdt_mobile_manipulator
– rcdt_gazebo (Gazebo models/launch)
– rcdt_joystick (joystick interfaces)
– rcdt_panther (+navigation)
– rcdt_sensors
– rcdt_utilities (launch utils, RViz configs)

a. Development & Deployment Layer
– Docker Engine & Devcontainer
– CI/CD Workflows (Lint, Docs, Docker Build)
b. Workflow Orchestrator
– Pyflow Core Engine
– Graph definitions (pyflow/graphs)
– Package plugins (pyflow/packages/RCDT)
c. ROS 2 Communication Layer
– Core message definitions (rcdt_messages)
– Topics, Services, Actions
d. Functional Subsystems (each as a module of ROS 2 nodes & plugins)
1. Perception: rcdt_detection
2. Action Execution: rcdt_actions
3. Manipulator Control: rcdt_franka + rcdt_franka_moveit_config
4. Mobile Base + Manipulator: rcdt_mobile_manipulator
5. Simulation: rcdt_gazebo
6. Joystick Interface: rcdt_joystick
7. Navigation (Panther): rcdt_panther
8. Sensor Utilities: rcdt_sensors
9. General Utilities & RViz: rcdt_utilities

##### Relationships & Interactions
- Pyflow triggers sequences of ROS 2 actions by calling rcdt_actions through ROS 2 action clients.
- rcdt_detection publishes sensor topics (RGBD images, masks) using rcdt_sensors utilities.
- rcdt_messages defines the contract for all inter-package communication (topics/services/actions).
- rcdt_franka (and /panther) subscribe to commands (MoveHandToPose, MoveToConfiguration) and drive hardware or simulation via MoveIt or Gazebo plugins.
- rcdt_utilities provides shared launch files (rviz.launch, utils.launch) and helper libraries.
- CI pipelines build Docker images, run tests (conftest.py), lint code, and generate docs.

##### Architectural Patterns & Principles
- Modular ROS 2 microservices: each robot capability is its own package with clear message/service boundaries.
- Message-driven communication: topics for streaming data, services for RPC, actions for long-running tasks.
- Plugin architecture in Pyflow for extensibility (node_loader, pin_loader).
- Containerized development and reproducibility via Docker/devcontainer.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Development & Deployment Layer
    subgraph "Development & Deployment Layer"
        DevContainer["Devcontainer Config"]:::dev
        Dockerfiles["Dockerfiles"]:::dev
        CIWorkflows["CI/CD Workflows"]:::dev
        InstallScripts["Docker Install Scripts"]:::dev
    end

    %% Workflow Orchestrator
    subgraph "Workflow Orchestrator (Pyflow)"
        PyflowCore["Pyflow Core Engine"]:::blue
        DefaultConfig["Default Config"]:::blue
        GraphDefs["Graph Definitions"]:::blue
        RCDTPlugins["RCDT Package Plugins"]:::blue
    end

    %% ROS 2 Communication Layer
    subgraph "ROS 2 Communication Layer"
        RCDTMessages["rcdt_messages\n(action, srv, package.xml)"]:::purple
    end

    %% Functional Subsystems
    subgraph "Functional Subsystems"
        subgraph Perception
            rcdt_detection["rcdt_detection Nodes & Launch"]:::blue
        end
        subgraph ActionExecution
            rcdt_actions["rcdt_actions Nodes & Definitions"]:::blue
        end
        subgraph ManipulatorControl
            rcdt_franka["rcdt_franka Nodes & Config"]:::blue
            rcdt_franka_moveit["MoveIt Config"]:::blue
        end
        subgraph MobileManipulator
            rcdt_mobile["rcdt_mobile_manipulator"]:::blue
        end
        subgraph Simulation
            rcdt_gazebo["rcdt_gazebo Models & Launch"]:::blue
        end
        subgraph Joystick
            rcdt_joystick["rcdt_joystick Nodes & Launch"]:::blue
        end
        subgraph Navigation
            rcdt_panther["rcdt_panther Nodes & Config"]:::blue
        end
        subgraph SensorUtilities
            rcdt_sensors["rcdt_sensors Utilities & URDF"]:::blue
        end
        subgraph UtilitiesRViz
            rcdt_utilities["rcdt_utilities Libraries & Launch"]:::blue
        end
    end

    %% External Dependencies
    DockerEngine(["Docker Engine"]):::orange
    GazeboSimulator(["Gazebo Simulator"]):::orange
    FrankaRobot(["Franka Robot Hardware"]):::orange
    PantherUGV(["Panther UGV Hardware"]):::orange
    MoveItExt(["MoveIt!"]):::orange

    %% Relationships
    DevContainer -->|uses| DockerEngine
    Dockerfiles -->|build images| DockerEngine
    CIWorkflows -->|runs on| DockerEngine
    CIWorkflows -->|triggers| DevContainer

    PyflowCore -->|loads| DefaultConfig
    PyflowCore -->|executes| GraphDefs
    PyflowCore -->|extends via| RCDTPlugins
    PyflowCore -->|calls| rcdt_actions

    rcdt_actions -->|defines| RCDTMessages
    rcdt_detection -->|publishes| RCDTMessages
    rcdt_actions -->|subscribes| RCDTMessages
    rcdt_franka -->|subscribes| RCDTMessages
    rcdt_franka_moveit -->|interfaces| MoveItExt
    rcdt_franka -->|drives| FrankaRobot
    rcdt_gazebo -->|mirrors| FrankaRobot
    rcdt_gazebo -->|runs on| GazeboSimulator
    rcdt_panther -->|drives| PantherUGV

    PyflowCore -->|orchestrates| rcdt_detection
    PyflowCore -->|orchestrates| rcdt_franka
    PyflowCore -->|orchestrates| rcdt_mobile
    PyflowCore -->|orchestrates| rcdt_gazebo

    rcdt_sensors -->|used by| rcdt_detection
    rcdt_utilities -->|provides| rcdt_detection
    rcdt_utilities -->|provides| rcdt_actions

    %% Click Events
    click DevContainer "https://github.com/alliander-opensource/rcdt_robotics/blob/main/.devcontainer/devcontainer.json"
    click Dockerfiles "https://github.com/alliander-opensource/rcdt_robotics/tree/main/dockerfiles"
    click CIWorkflows "https://github.com/alliander-opensource/rcdt_robotics/blob/main/.github/workflows/docker-and-workspace.yml"
    click InstallScripts "https://github.com/alliander-opensource/rcdt_robotics/tree/main/dockerfiles/install_scripts"
    click PyflowCore "https://github.com/alliander-opensource/rcdt_robotics/blob/main/pyflow/__init__.py"
    click DefaultConfig "https://github.com/alliander-opensource/rcdt_robotics/blob/main/pyflow/default_config/config.ini"
    click GraphDefs "https://github.com/alliander-opensource/rcdt_robotics/blob/main/pyflow/graphs/pick_brick.pygraph"
    click RCDTPlugins "https://github.com/alliander-opensource/rcdt_robotics/blob/main/pyflow/packages/RCDT/Core/core.py"
    click RCDTMessages "https://github.com/alliander-opensource/rcdt_robotics/blob/main/ros2_ws/src/rcdt_messages/action/Sequence.action"
    click rcdt_detection "https://github.com/alliander-opensource/rcdt_robotics/blob/main/ros2_ws/src/rcdt_detection/rcdt_detection/*.py"
    click rcdt_actions "https://github.com/alliander-opensource/rcdt_robotics/blob/main/ros2_ws/src/rcdt_actions/rcdt_actions/actions/actions.py"
    click rcdt_franka "https://github.com/alliander-opensource/rcdt_robotics/blob/main/ros2_ws/src/rcdt_franka/rcdt_franka/*.py"
    click rcdt_franka_moveit "https://github.com/alliander-opensource/rcdt_robotics/blob/main/ros2_ws/src/rcdt_franka_moveit_config/launch/moveit.launch.py"
    click rcdt_mobile "https://github.com/alliander-opensource/rcdt_robotics/blob/main/ros2_ws/src/rcdt_mobile_manipulator/rcdt_mobile_manipulator/*.py"
    click rcdt_gazebo "https://github.com/alliander-opensource/rcdt_robotics/blob/main/ros2_ws/src/rcdt_gazebo/launch/gazebo_robot.launch.py"
    click rcdt_joystick "https://github.com/alliander-opensource/rcdt_robotics/blob/main/ros2_ws/src/rcdt_joystick/launch/joystick.launch.py"
    click rcdt_panther "https://github.com/alliander-opensource/rcdt_robotics/blob/main/ros2_ws/src/rcdt_panther/rcdt_panther/*.py"
    click rcdt_sensors "https://github.com/alliander-opensource/rcdt_robotics/blob/main/ros2_ws/src/rcdt_sensors/src_py/*.py"
    click rcdt_utilities "https://github.com/alliander-opensource/rcdt_robotics/blob/main/ros2_ws/src/rcdt_utilities/rcdt_utilities/*.py"

    %% Styles
    classDef dev fill:#a6f3a6,stroke:#333,stroke-width:1px
    classDef blue fill:#a8d8f8,stroke:#333,stroke-width:1px
    classDef orange fill:#f8c68e,stroke:#333,stroke-width:1px
    classDef purple fill:#d5a3f7,stroke:#333,stroke-width:1px
```
