# jgitsol/robot_portfolio architecture

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

- Interactive diagram: https://gitdiagram.com/jgitsol/robot_portfolio
- Repository: https://github.com/jgitsol/robot_portfolio

## Overview

##### Project type and purpose
- This is an open-source, Python-based simulation tool (“robot_arm”) built on top of a reusable “robot_arm_simulator” library, plus a separate “LightPath” route-optimization module in the same mono-repo.
- The primary user-facing component is a PyBullet-based production line simulator with multiple 6-DOF arms, specialized grippers, a conveyor subsystem, and real-time 3D visualization.

##### File structure
- Top-level “v_beta/robot_arm_simulator” is a standalone Python package:
- config/ – simulation.yaml and loader
- src/robot_arm_simulator/… – core modules (config_loader, trajectory_planner, simulation, control, grippers, robots, utils)
- tests – unit tests for every sub-component
- Top-level “v_beta/src/robot_arm” is the demo package:
- demo.py, production_line.py, robot.py, grippers.py, ur5_robot.py – user scripts and classes that orchestrate the simulator library
- models/ – URDF and 3D files for robots, grippers, items
- “v_beta/src/lightpath” is a separate route-optimization engine (basic_use.py, core.py).
- Standard config files, setup.py, requirements.txt, pytest.ini, and CLI entry points are present.

##### Key insights from README
- The “robot_arm” CLI/demo loads a YAML config, spawns several robotic arms with different grippers on a conveyor, runs pick-and-place via PyBullet, and renders the scene.
- Dependencies: Python 3.8+, PyBullet, NumPy, PyYAML.

a. Main components
- User Interface / CLI (“robot-arm-demo”)
- Demo orchestration layer (“robot_arm” package)
- Simulation Core Library (“robot_arm_simulator”)
– Config Loader
– World & Environment (conveyor, sensors)
– Robot & Gripper classes
– Trajectory Planner / Control loop
– Physics engine wrapper (PyBullet)
– Utilities (logging, math)
- Model Repository (URDF, .glb files)
- Visualization & Rendering (PyBullet GUI)
- External Dependencies (PyBullet, NumPy, PyYAML)

b. Relationships and data flows
1. CLI → Demo orchestrator loads config via Config Loader
2. Demo instantiates Environment + Robots + Grippers
3. Orchestrator calls Simulation Core → hands off to PyBullet
4. Simulation loop:
– Sensors read world state → feed into Trajectory Planner
– Planner outputs joint commands → Control → actuates robot models in PyBullet
– PyBullet updates physics → updated world state
5. Visualization taps into PyBullet GUI each tick
6. At shutdown, orchestrator collects logs/results

c. Architectural patterns & design principles
- Modular library + thin orchestration layer
- Config-driven initialization (YAML)
- Clear separation: Model data (URDF) vs. code vs. config
- Strategy/plug-in pattern for grippers and robot kinematics
- Test-first design: extensive pytest suite for each module

d. Key technologies & libraries
- Python 3.8+
- PyBullet (physics + rendering)
- NumPy (math ops)
- PyYAML (config loader)
- Hypothesis / pytest (testing)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Demo Orchestration Layer
    subgraph "robot_arm demo"
        direction TB
        CLI["CLI / main.py"]:::demo
        Demo["demo.py"]:::demo
        ProdLine["production_line.py"]:::demo
        RobotDef["robot.py"]:::demo
        GrippersDemo["grippers.py"]:::demo
        UR5Demo["ur5_robot.py"]:::demo
        RobotCfg["robot_config.py"]:::demo
    end

    %% Simulation Core Library
    subgraph "robot_arm_simulator library"
        direction TB
        ConfigLoader["Config Loader"]:::core
        TrajPlanner["Trajectory Planner"]:::core
        Environment["Environment"]:::core
        Conveyor["Conveyor"]:::core
        Sensors["Sensors"]:::core
        BaseRobot["Base Robot"]:::core
        UR5Sim["UR5 Robot"]:::core
        BaseGripper["Base Gripper"]:::core
        ParGripper["Parallel Gripper"]:::core
        Utils["Utilities"]:::core
    end

    %% Models & Assets
    subgraph "Model Repository" 
        direction TB
        GripperModels["Gripper Models"]:::assets
        TargetItems["Target Items"]:::assets
        URDF["UR5 URDF"]:::assets
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        PyBullet["PyBullet"]:::ext
        NumPy["NumPy"]:::ext
        PyYAML["PyYAML"]:::ext
    end

    %% LightPath Module
    subgraph "LightPath Module"
        direction TB
        LPCore["core.py"]:::core
        LPBasic["basic_use.py"]:::core
    end

    %% Relationships
    CLI -->|"invoke"| Demo
    Demo -.->|"load config"| ConfigLoader
    Demo -->|"initialize"| Environment
    Demo -->|"spawn robots"| BaseRobot
    Demo -->|"attach grippers"| BaseGripper
    Demo -->|"use UR5 implementation"| UR5Sim
    Demo -->|"use parallel gripper"| ParGripper
    Demo -.->|"load models"| GripperModels
    Demo -.->|"load models"| TargetItems
    Demo -.->|"load URDF"| URDF

    Environment -->|"create conveyor"| Conveyor
    Environment -->|"attach sensors"| Sensors
    Environment -->|"physics & render"| PyBullet
    Sensors -->|"world state"| TrajPlanner
    TrajPlanner -->|"joint commands"| BaseRobot
    BaseRobot -->|"actuate"| Environment

    %% LightPath integration
    LPCore -.->|"optimized path"| TrajPlanner

    %% External dependencies usage
    ConfigLoader -->|"parse YAML"| PyYAML
    TrajPlanner -->|"math ops"| NumPy
    Environment -->|"physics & GUI"| PyBullet

    %% Click events
    click CLI "https://github.com/jgitsol/robot_portfolio/blob/main/v_beta/src/robot_arm/main.py"
    click Demo "https://github.com/jgitsol/robot_portfolio/blob/main/v_beta/src/robot_arm/demo.py"
    click ProdLine "https://github.com/jgitsol/robot_portfolio/blob/main/v_beta/src/robot_arm/production_line.py"
    click RobotDef "https://github.com/jgitsol/robot_portfolio/blob/main/v_beta/src/robot_arm/robot.py"
    click GrippersDemo "https://github.com/jgitsol/robot_portfolio/blob/main/v_beta/src/robot_arm/grippers.py"
    click UR5Demo "https://github.com/jgitsol/robot_portfolio/blob/main/v_beta/src/robot_arm/ur5_robot.py"
    click RobotCfg "https://github.com/jgitsol/robot_portfolio/blob/main/v_beta/src/robot_arm/robot_config.py"
    click ConfigLoader "https://github.com/jgitsol/robot_portfolio/blob/main/v_beta/robot_arm_simulator/src/robot_arm_simulator/config/config_loader.py"
    click TrajPlanner "https://github.com/jgitsol/robot_portfolio/blob/main/v_beta/robot_arm_simulator/src/robot_arm_simulator/control/trajectory_planner.py"
    click Environment "https://github.com/jgitsol/robot_portfolio/blob/main/v_beta/robot_arm_simulator/src/robot_arm_simulator/simulation/environment.py"
    click Conveyor "https://github.com/jgitsol/robot_portfolio/blob/main/v_beta/robot_arm_simulator/src/robot_arm_simulator/simulation/conveyor.py"
    click Sensors "https://github.com/jgitsol/robot_portfolio/blob/main/v_beta/robot_arm_simulator/src/robot_arm_simulator/simulation/sensors.py"
    click BaseRobot "https://github.com/jgitsol/robot_portfolio/blob/main/v_beta/robot_arm_simulator/src/robot_arm_simulator/robots/base_robot.py"
    click UR5Sim "https://github.com/jgitsol/robot_portfolio/blob/main/v_beta/robot_arm_simulator/src/robot_arm_simulator/robots/ur5_robot.py"
    click BaseGripper "https://github.com/jgitsol/robot_portfolio/blob/main/v_beta/robot_arm_simulator/src/robot_arm_simulator/grippers/base_gripper.py"
    click ParGripper "https://github.com/jgitsol/robot_portfolio/blob/main/v_beta/robot_arm_simulator/src/robot_arm_simulator/grippers/parallel_gripper.py"
    click LPCore "https://github.com/jgitsol/robot_portfolio/blob/main/v_beta/src/lightpath/core.py"
    click LPBasic "https://github.com/jgitsol/robot_portfolio/blob/main/v_beta/src/lightpath/basic_use.py"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef demo fill:#DFFFE0,stroke:#228B22,color:#228B22;
    classDef ext fill:#FFE4B5,stroke:#FF8C00,color:#FF8C00;
    classDef assets fill:#E0E0E0,stroke:#666666,color:#333333;
```
