# roben-aast/shell_controller_2025 architecture

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

- Interactive diagram: https://gitdiagram.com/roben-aast/shell_controller_2025
- Repository: https://github.com/roben-aast/shell_controller_2025

## Overview

##### Project Type & Purpose
- This is a robotics-simulation + reinforcement-learning (RL) training pipeline.
- It integrates:
- CARLA (autonomous‐driving simulator)
- ROS (Robot Operating System) nodes & bridges
- A custom OpenAI‐Gym wrapper (`gym_carla`)
- An RL agent (PPO) with hyperparameter tuning (Optuna)
- C++ simulation nodes (shell_simulation) built via ROS/CMake
- Python package modules for brain, training, utilities

##### Top-Level Components
a. External Simulator
- CARLA UE4 process (launched via `CarlaUE4.sh`)
b. ROS Layer
- carla_shell_bridge (in `sem-apc-ros-bridge` / `roslaunch carla_shell_bridge`)
- shell_simulation node (in `shell_simulation/src`)
- Any additional ROS interfaces (e.g., `sem-apc-carla-interface`)
c. Gym Environment
- `roben_ai/ai_src/gym_carla` (custom Gym env)
- `make_env.py` entrypoint
d. RL Agent & Training
- Models: `actor.py`, `critic.py`, `backbone.py`
- Trainer: `training/trainer.py`, `training/loss.py`
- Hyperparameter search: `optuna_study.py`
- Logs & DB: `ppo_carla.db`, TensorBoard events under `runs/`
e. Configuration & Utilities
- `roben_ai/config/hyperparams.py`
- Utils: `utils/types.py`
- CLI scripts: `scripts/install_requirements.py`
f. Packaging & Testing
- `setup.py` / `setup.cfg` / `requirements.txt`
- Tests in `test/`

##### Relationships & Data Flow
1. CARLA simulator publishes sensor data & world state over ROS topics.
2. `carla_shell_bridge` subscribes to CARLA topics, republishes them into ROS.
3. `shell_simulation` node reads sensor topics, may inject control or logging.
4. Gym wrapper (`gym_carla/envs/carla_env.py`) acts as ROS subscriber/publisher:
- Receives observations
- Sends action messages back into ROS
5. The RL agent (trainer) calls Gym’s `step()`, passing actions, receives observations + rewards.
6. `trainer.py` updates `actor`/`critic` networks, logs scalar metrics to TensorBoard, saves models.
7. Optuna script wraps the trainer to iterate hyperparameter trials, reading/writing `ppo_carla.db`.
8. Configuration parameters drive network architecture and training loop.

##### Architectural Patterns & Principles
- Modular layering: Simulator ↔ ROS middleware ↔ Gym wrapper ↔ Agent/trainer
- Publish/subscribe (ROS topics) decouples simulation from agent.
- Client–server style for Gym→Trainer interactions.
- Separation of concerns:
- C++ code for simulation nodes
- Python code for RL & wrappers
- Extensibility: Hyperparameters in standalone config; new models can be added under `models/`.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Simulator Layer
    CarlaUE4["CarlaUE4<br/>(UE4/C++)"]:::simulator

    %% ROS Middleware Layer
    subgraph "ROS Middleware"
        direction TB
        CARLABridge["carla_shell_bridge<br/>(ROS Bridge)"]:::ros
        CARLAInterface["sem-apc-carla-interface<br/>(ROS Interface)"]:::ros
        ShellSimNode["shell_simulation<br/>(C++ Node)"]:::ros
    end

    %% Gym Environment Layer
    subgraph "Gym Environment"
        direction TB
        GymRoot["gym_carla<br/>(Custom Gym Wrapper)"]:::gym
        CarlaEnv["carla_env.py"]:::gym
        MakeEnv["make_env.py"]:::gym
    end

    %% Agent & Training Layer
    subgraph "RL Agent & Training"
        direction TB
        Actor["actor.py"]:::agent
        Critic["critic.py"]:::agent
        Backbone["backbone.py"]:::agent
        Trainer["trainer.py"]:::agent
        Loss["loss.py"]:::agent
        Optuna["optuna_study.py"]:::agent
    end

    %% Configuration & Utilities Layer
    subgraph "Configuration & Utilities"
        direction TB
        Hyperparams["hyperparams.py"]:::util
        Types["types.py"]:::util
        Brain["brain.py"]:::util
        Installer["install_requirements.py"]:::util
    end

    %% Storage Layer
    subgraph "Storage"
        direction TB
        DB["ppo_carla.db"]:::storage
        TBLogs["TensorBoard Logs"]:::storage
    end

    %% Packaging & Testing Layer
    subgraph "Packaging & Testing"
        direction TB
        SetupPy["setup.py"]:::util
        ReqTxt["requirements.txt"]:::util
        TestFlake8["test_flake8.py"]:::util
        TestPep["test_pep257.py"]:::util
    end

    %% Data Flows
    CarlaUE4 -->|"sensor data"| CARLABridge
    CARLABridge -->|"ROS topics"| ShellSimNode
    CARLABridge -->|"ROS topics"| GymRoot
    ShellSimNode -->|"processed data"| GymRoot
    GymRoot -->|"obs/actions"| CarlaEnv
    CarlaEnv -->|"step()"| Trainer
    Trainer -->|"update nets"| Actor
    Trainer -->|"update nets"| Critic
    Trainer -->|"update nets"| Backbone
    Trainer -->|"compute loss"| Loss
    Optuna -->|"hyperparam trials"| Trainer
    Trainer -->|"log metrics"| TBLogs
    Trainer -->|"save metrics"| DB
    Hyperparams -->|"config"| Trainer
    Types -->|"typing"| Trainer
    Brain -->|"orchestrate"| Trainer
    Installer -->|"setup env"| GymRoot
    SetupPy -->|"package"| GymRoot
    ReqTxt -->|"dependencies"| GymRoot
    TestFlake8 -->|"lint tests"| GymRoot
    TestPep -->|"doc tests"| GymRoot

    %% Click Events
    click CARLABridge "https://github.com/roben-aast/shell_controller_2025/tree/main/sem-apc-ros-bridge/"
    click ShellSimNode "https://github.com/roben-aast/shell_controller_2025/blob/main/shell_simulation/launch/shell_simulation.launch"
    click ShellSimNode "https://github.com/roben-aast/shell_controller_2025/blob/main/shell_simulation/src/shell_simulation_node.cpp"
    click GymRoot "https://github.com/roben-aast/shell_controller_2025/tree/main/roben_ai/ai_src/gym_carla/"
    click CarlaEnv "https://github.com/roben-aast/shell_controller_2025/blob/main/roben_ai/ai_src/gym_carla/envs/carla_env.py"
    click MakeEnv "https://github.com/roben-aast/shell_controller_2025/blob/main/roben_ai/ai_src/gym_carla/make_env.py"
    click Actor "https://github.com/roben-aast/shell_controller_2025/blob/main/roben_ai/ai_src/models/actor.py"
    click Critic "https://github.com/roben-aast/shell_controller_2025/blob/main/roben_ai/ai_src/models/critic.py"
    click Backbone "https://github.com/roben-aast/shell_controller_2025/blob/main/roben_ai/ai_src/models/backbone.py"
    click Trainer "https://github.com/roben-aast/shell_controller_2025/blob/main/roben_ai/ai_src/training/trainer.py"
    click Loss "https://github.com/roben-aast/shell_controller_2025/blob/main/roben_ai/ai_src/training/loss.py"
    click Optuna "https://github.com/roben-aast/shell_controller_2025/blob/main/roben_ai/ai_src/optuna_study.py"
    click DB "https://github.com/roben-aast/shell_controller_2025/blob/main/roben_ai/ai_src/ppo_carla.db"
    click Hyperparams "https://github.com/roben-aast/shell_controller_2025/blob/main/roben_ai/config/hyperparams.py"
    click Types "https://github.com/roben-aast/shell_controller_2025/blob/main/roben_ai/ai_src/utils/types.py"
    click Brain "https://github.com/roben-aast/shell_controller_2025/blob/main/roben_ai/roben_ai/brain.py"
    click Installer "https://github.com/roben-aast/shell_controller_2025/blob/main/roben_ai/scripts/install_requirements.py"
    click SetupPy "https://github.com/roben-aast/shell_controller_2025/blob/main/roben_ai/setup.py"
    click ReqTxt "https://github.com/roben-aast/shell_controller_2025/blob/main/roben_ai/requirements.txt"
    click TestFlake8 "https://github.com/roben-aast/shell_controller_2025/blob/main/roben_ai/test/test_flake8.py"
    click TestPep "https://github.com/roben-aast/shell_controller_2025/blob/main/roben_ai/test/test_pep257.py"

    %% Styles
    classDef simulator fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef ros fill:#FFA500,stroke:#333,stroke-width:1px
    classDef gym fill:#90EE90,stroke:#333,stroke-width:1px
    classDef agent fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef util fill:#98FB98,stroke:#333,stroke-width:1px
    classDef storage fill:#FFD700,stroke:#333,stroke-width:1px
```
