# robesafe-uah/rl-intersections architecture

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

- Interactive diagram: https://gitdiagram.com/robesafe-uah/rl-intersections
- Repository: https://github.com/robesafe-uah/rl-intersections

## Overview

##### Project Type and Purpose
- The project is titled “rl-intersections,” which immediately suggests that it is focused on reinforcement learning (RL) in the context of traffic intersections.
- It combines simulation environments (using SUMO and likely CARLA) with RL training elements. Additionally, there is significant ROS integration (as seen in the "catkin_ws" directory structure) for messaging, control, mapping, and planning—which points to an autonomous or assisted driving simulation/testbed for handling intersections.

##### Main Components
a. Simulation/Environment Modules:
- The “Intersection” folder in src contains several Python files (e.g., IntersectionCarlaEnvFeatures, IntersectionSumoEnv, IntersectionSumoEnvFeatures) and a “sumo_config” directory with XML configuration files for SUMO. These files indicate that the project simulates intersection scenarios using SUMO (and integrates features for CARLA).
b. Reinforcement Learning and Training:
- The “Training” directory holds RL-related files, including model training scripts or outputs (like "monitor.csv") and configuration settings. This module represents the RL agent training pipeline.
c. ROS Integration (catkin Workspace):
- The "catkin_ws" directory outlines several ROS packages:
- ros-carla-msgs: Custom message definitions for CARLA integration.
- t4ac_control: Likely responsible for vehicle control (includes launch files and C++ nodes).
- t4ac_mapping: Contains mapping tools and utilities (parsers, tests, and map files in various formats such as osm/xodr).
- t4ac_msgs_ros: Additional custom ROS message definitions.
- t4ac_planning: Encompasses path planning or navigation modules, including components for global and dummy planners, simulation of navigation, and integration with mapping modules.
- These packages interact to deliver real-time sensor messaging, control commands, and planning data flowing between the simulation environment and the RL agent(s).

##### Relationships and Interactions
- The Simulation Module (Intersection) provides the environment data (traffic, intersection configuration) to the RL Training module.
- The RL Training module, in turn, likely generates policies or control commands.
- ROS acts as an integration layer:
- ROS messages (defined in ros-carla-msgs and t4ac_msgs_ros) serve as the communication backbone for exchanging data between simulation, control, mapping, and planning nodes.
- The “t4ac_control” nodes receive commands (potentially from the RL agent’s output) and apply them in simulation.
- “t4ac_mapping” modules work on environment mapping and route / waypoint generation, which are critical inputs for the planning stage.
- “t4ac_planning” implements planning algorithms to produce high-level navigation commands, likely integrating with both mapping data and the RL control feedback.
- Data flows are bidirectional:
- The environment (SUMO/CARLA simulation) provides state feedback.
- Control/planning modules send trajectory or command outputs.
- ROS topics and services tie these layers together with directional message flows (e.g., sensor readings coming into planning and control nodes, planning outputs sent to simulation and visualization modules).

##### Architectural Patterns and Key Design Principles
- Modular and Layered Architecture: Clear separation between environment simulation, RL training, and ROS-based control/mapping/planning modules.
- Microservices or distributed system design style within ROS: Individual ROS packages (nodes) each handle a subset of the responsibilities.
- Integration of simulation technologies (SUMO, CARLA) with robotics middleware (ROS) supports testing in safe, virtualized intersection environments.
- Use of standardized messaging systems (custom msg definitions) ensures loose coupling and clearer interfaces between components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Simulation & Environment"
        SIM["Intersection Simulation Module"]:::sim
    end

    subgraph "Reinforcement Learning"
        TRAIN["RL Training Module"]:::training
    end

    subgraph "ROS Integration"
        MSG["ROS Messaging (ros-carla-msgs)"]:::ros
        CTRL["ROS Control Module (t4ac_control)"]:::ros
        MAP["ROS Mapping Module (t4ac_mapping)"]:::ros
        EXTRA["ROS Extra Messaging (t4ac_msgs_ros)"]:::ros
        PLAN["ROS Planning Module (t4ac_planning)"]:::ros
    end

    %% Data Flows Between Layers
    SIM -->|"state_observations"| TRAIN
    TRAIN -->|"action_commands"| CTRL
    PLAN -->|"navigation"| SIM

    %% Internal ROS Communications
    MSG -->|"msg_defs"| CTRL
    CTRL <-->|"feedback"| MAP
    MAP -->|"map_data"| PLAN
    PLAN -->|"plan_commands"| CTRL
    CTRL <-->|"ext_msgs"| EXTRA

    %% Styles
    classDef sim fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef training fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef ros fill:#cce5ff,stroke:#004d99,stroke-width:2px;

    %% Click Events
    click SIM "https://github.com/robesafe-uah/rl-intersections/tree/master/src/Intersection"
    click TRAIN "https://github.com/robesafe-uah/rl-intersections/tree/master/src/Training"
    click MSG "https://github.com/robesafe-uah/rl-intersections/tree/master/src/catkin_ws/src/ros-carla-msgs"
    click CTRL "https://github.com/robesafe-uah/rl-intersections/tree/master/src/catkin_ws/src/t4ac_control"
    click MAP "https://github.com/robesafe-uah/rl-intersections/tree/master/src/catkin_ws/src/t4ac_mapping"
    click EXTRA "https://github.com/robesafe-uah/rl-intersections/tree/master/src/catkin_ws/src/t4ac_msgs_ros"
    click PLAN "https://github.com/robesafe-uah/rl-intersections/tree/master/src/catkin_ws/src/t4ac_planning"
```
