# reiniscimurs/drl-robot-navigation-ros2 architecture

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

- Interactive diagram: https://gitdiagram.com/reiniscimurs/drl-robot-navigation-ros2
- Repository: https://github.com/reiniscimurs/drl-robot-navigation-ros2

## Overview

##### Project type and purpose
- A robotics full‐stack application combining:
– Gazebo simulation (virtual environment)
– ROS2 middleware for robot communication
– Deep Reinforcement Learning (TD3 & SAC agents) implemented in Python/PyTorch
– Visualization (RViz) and logging (Tensorboard)

##### File structure
- src/drl_navigation_ros2 – core Python DRL modules (SAC, TD3, replay_buffer, pretrain_utils, utils, ros_nodes)
- src/turtlebot3_description – URDF models and meshes for TurtleBot3 robots
- src/turtlebot3_simulations – Gazebo world definitions, robot plugins, launch files
- tests – unit tests for default behaviors
- pyproject.toml, colcon build files – build and packaging configuration

##### README insights
- ROS2 Foxy + Python3.8 + PyTorch + Tensorboard are core dependencies
- Training workflow: launch Gazebo → launch training script → monitor via RViz & Tensorboard
- ROS2 nodes and DRL code interoperate via ROS2 topics

##### Main components and interactions (to show
a. Gazebo Simulator
– Hosts the world (obstacles, robot model)
– Publishes simulated laser scans (/scan), odometry (/odom)
b. ROS2 Middleware (DDS)
– Manages topics, services, parameters
– Launch files (ros2_drl.launch.py) coordinate nodes
c. DRL Training Node (train.py)
– Contains agent loop: observe → compute action → publish cmd_vel
– Uses SAC and/or TD3 modules under src/drl_navigation_ros2/SAC and /TD3
– Interfaces to replay_buffer module to store transitions
– Calls pretrain_utils to load or initialize network weights
d. Replay Buffer (replay_buffer.py)
– Data store for (state, action, reward, next_state) tuples
e. Neural‐Network Modules
– SAC_actor.py, SAC_critic.py, TD3.py – define policy and value networks
f. Hardcoded Model Fallback (hardcoded_model.py)
– Provides baseline control policy if needed
g. Visualization & Logging
– RViz2 subscribes to robot state topics for 3D visualization
– Tensorboard reads logs in runs/ directory for training metrics
h. External Configuration
– data.yml (assets) for hyperparameters
– ROS parameters set via launch files

##### Architectural patterns and design principles
- Modular separation between:
– Simulation environment (Gazebo)
– Middleware (ROS2 nodes, topics)
– Learning algorithms (agent classes, replay buffer)
– Visualization/Logging (RViz, Tensorboard)
- Clear producer–consumer flow (Gazebo → DRL node → Gazebo)
- Dependency inversion via ROS2 topics, enabling hot‐swapping agents

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Simulation Environment"
    GazeboSim["Gazebo Simulator"]:::env
    Models["Models"]:::env
    Worlds["Worlds"]:::env
    GazeboSim --> Models
    GazeboSim --> Worlds
  end

  click Models "https://github.com/reiniscimurs/drl-robot-navigation-ros2/tree/main/src/turtlebot3_simulations/turtlebot3_gazebo/models"
  click Worlds "https://github.com/reiniscimurs/drl-robot-navigation-ros2/tree/main/src/turtlebot3_simulations/turtlebot3_gazebo/worlds"

  subgraph "ROS2 Middleware"
    LaunchGazebo["Gazebo Launch Integration\n(ros2_drl.launch.py)"]:::middleware
    RobotStatePub["Robot State Publisher\n(robot_state_publisher.launch.py)"]:::middleware
    URDF["URDF Models & Meshes"]:::middleware
    GazeboSim -->|"/scan,/odom"| LaunchGazebo
    LaunchGazebo --> RobotStatePub
    RobotStatePub --> URDF
  end

  click LaunchGazebo "https://github.com/reiniscimurs/drl-robot-navigation-ros2/blob/main/src/turtlebot3_simulations/turtlebot3_gazebo/launch/ros2_drl.launch.py"
  click RobotStatePub "https://github.com/reiniscimurs/drl-robot-navigation-ros2/blob/main/src/turtlebot3_simulations/turtlebot3_gazebo/launch/robot_state_publisher.launch.py"
  click URDF "https://github.com/reiniscimurs/drl-robot-navigation-ros2/tree/main/src/turtlebot3_description/urdf"
  click URDF "https://github.com/reiniscimurs/drl-robot-navigation-ros2/tree/main/src/turtlebot3_description/meshes"

  subgraph "DRL Training Pipeline"
    TrainNode["Training Node\n(train.py)"]:::learning
    ROSNodes["ROS2 Nodes & Topics\n(ros_nodes.py)"]:::learning
    SACActor["SAC Actor\n(SAC_actor.py)"]:::learning
    SACCritic["SAC Critic\n(SAC_critic.py)"]:::learning
    SACCore["SAC Core & Utils\n(SAC.py, SAC_utils.py)"]:::learning
    TD3Module["TD3 Module\n(TD3.py)"]:::learning
    ReplayBuffer["Replay Buffer\n(replay_buffer.py)"]:::datastore
    Pretrain["Pretraining Utils\n(pretrain_utils.py)"]:::learning
    Hardcoded["Hardcoded Policy\n(hardcoded_model.py)"]:::learning
    Utils["Helper & Utils\n(utils.py, lib.py)"]:::learning
    Config["Hyperparameters\n(data.yml)"]:::config

    GazeboSim -->|sensor topics| ROSNodes
    ROSNodes -->|publish cmd_vel| GazeboSim
    TrainNode --> ROSNodes
    TrainNode --> SACActor
    TrainNode --> SACCritic
    TrainNode --> SACCore
    TrainNode --> TD3Module
    TrainNode --> ReplayBuffer
    TrainNode --> Pretrain
    TrainNode --> Hardcoded
    TrainNode --> Utils
    TrainNode --> Config
    TrainNode -->|writes metrics| TB
  end

  click TrainNode "https://github.com/reiniscimurs/drl-robot-navigation-ros2/blob/main/src/drl_navigation_ros2/train.py"
  click ROSNodes "https://github.com/reiniscimurs/drl-robot-navigation-ros2/blob/main/src/drl_navigation_ros2/ros_nodes.py"
  click SACActor "https://github.com/reiniscimurs/drl-robot-navigation-ros2/blob/main/src/drl_navigation_ros2/SAC/SAC_actor.py"
  click SACCritic "https://github.com/reiniscimurs/drl-robot-navigation-ros2/blob/main/src/drl_navigation_ros2/SAC/SAC_critic.py"
  click SACCore "https://github.com/reiniscimurs/drl-robot-navigation-ros2/blob/main/src/drl_navigation_ros2/SAC/SAC.py"
  click SACCore "https://github.com/reiniscimurs/drl-robot-navigation-ros2/blob/main/src/drl_navigation_ros2/SAC/SAC_utils.py"
  click TD3Module "https://github.com/reiniscimurs/drl-robot-navigation-ros2/blob/main/src/drl_navigation_ros2/TD3/TD3.py"
  click ReplayBuffer "https://github.com/reiniscimurs/drl-robot-navigation-ros2/blob/main/src/drl_navigation_ros2/replay_buffer.py"
  click Pretrain "https://github.com/reiniscimurs/drl-robot-navigation-ros2/blob/main/src/drl_navigation_ros2/pretrain_utils.py"
  click Hardcoded "https://github.com/reiniscimurs/drl-robot-navigation-ros2/blob/main/src/drl_navigation_ros2/hardcoded_model.py"
  click Utils "https://github.com/reiniscimurs/drl-robot-navigation-ros2/blob/main/src/drl_navigation_ros2/utils.py"
  click Utils "https://github.com/reiniscimurs/drl-robot-navigation-ros2/blob/main/src/drl_navigation_ros2/lib.py"
  click Config "https://github.com/reiniscimurs/drl-robot-navigation-ros2/blob/main/src/drl_navigation_ros2/assets/data.yml"

  subgraph "Visualization & Logging"
    RViz["RViz2"]:::viz
    ModelRViz["TB3 Model RViz\n(model.rviz)"]:::viz
    DemoRViz["Gazebo/RVIZ Demo View\n(tb3_gazebo.rviz)"]:::viz
    TB["Tensorboard\n(logs)"]:::viz
    LogDir["Logging Dir\n(log/latest)"]:::datastore

    RViz --> ModelRViz
    RViz --> DemoRViz
    TB -->|reads logs| LogDir
  end

  click ModelRViz "https://github.com/reiniscimurs/drl-robot-navigation-ros2/blob/main/src/turtlebot3_description/rviz/model.rviz"
  click DemoRViz "https://github.com/reiniscimurs/drl-robot-navigation-ros2/blob/main/src/turtlebot3_simulations/turtlebot3_gazebo/rviz/tb3_gazebo.rviz"
  click LogDir "https://github.com/reiniscimurs/drl-robot-navigation-ros2/tree/main/log/latest"

  subgraph "Build & Config"
    PyProj["pyproject.toml"]:::config
    TestEnv["src/test.env"]:::config
  end

  classDef env fill:#ADD8E6,stroke:#0000FF
  classDef middleware fill:#90EE90,stroke:#008000
  classDef learning fill:#FFFFE0,stroke:#CCCC00
  classDef datastore fill:#FFA500,stroke:#FF4500
  classDef viz fill:#DDA0DD,stroke:#800080
  classDef config fill:#F0F0F0,stroke:#A9A9A9
```
