# joao-borrego/grasp architecture

> Architecture diagram of the GitHub repository joao-borrego/grasp, 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/joao-borrego/grasp
- Repository: https://github.com/joao-borrego/grasp

## Overview

##### Project Type and Purpose
- This is a robotics simulation toolkit (“GRASP”) for dynamic grasp simulation inside the Gazebo simulator, using the DART physics engine.
- It provides a C++ core library (grasp/), Gazebo plugins (plugins/), message definitions (msgs/), models (models/), configuration files (cfg/), example binaries (examples/), and helper scripts (scripts/, datasets/, utils/).

##### Architectural Analysis
- Top-level components:
- Core C++ Library (“grasp/”)
- Gazebo Plugins (“plugins/”)
- Protobuf Message Interface (“msgs/”)
- Models & Worlds (“models/”, “worlds/”)
- Configuration Management (“cfg/”)
- Example Executables (“examples/”)
- Data-preparation & Utility Scripts (“scripts/”, “datasets/”, “utils/”)
- Build & Deployment (CMakeLists.txt, cmake/, deps/)
- Architectural patterns:
- Plugin-based extension of Gazebo
- Pub/Sub messaging via Protobuf topics
- Modular CMake build
- Separation of simulation assets (models, worlds) vs. code
- External dependencies:
- Gazebo simulator
- DART physics engine
- Protobuf (for msgs/)
- Python (for scripts, dataset conversion)

##### Essential Elements to Capture
- All major directories as logical components
- Data flow via Protobuf topics
- Configurable parameters reading from cfg/
- Build/deploy process (CMake, deps/install_deps.sh) as a side note
- Example clients interacting over the message bus
- Model/dataset preprocessing pipeline

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Simulation Engine Layer
    subgraph "Simulation Engine"
        style SimulationEngine fill:#eeeeee,stroke:#333,stroke-width:1px
        Gazebo["Gazebo Simulator"]:::sim
        DART["DART Physics Engine"]:::sim
    end

    %% Extension Layer
    subgraph "Extension Layer"
        Core["GRASP Core Library"]:::core
        Plugins["Gazebo Plugins"]:::core
    end

    %% Messaging Layer
    subgraph "Messaging Layer"
        Msg["Protobuf Message Interface"]:::msg
    end

    %% Assets and Configuration
    subgraph "Assets / Configuration"
        Models["Models"]:::asset
        Worlds["Worlds"]:::asset
        Config["Configuration Loader (cfg/)"]:::asset
    end

    %% Entry Points
    subgraph "Entry Points"
        Examples["Example Binaries"]:::entry
        Scripts["Scripts"]:::entry
        Datasets["Datasets"]:::entry
        Utils["Utils"]:::entry
    end

    %% Build & Deployment
    Build["Build & Deployment"]:::build

    %% Relationships
    Gazebo -->|"loads"| Models
    Gazebo -->|"loads"| Worlds
    Gazebo -->|"hosts plugins"| Plugins
    Plugins -->|"invokes functions"| Core
    Plugins -->|"pub/sub on topics"| Msg
    Core -->|"through plugins"| Gazebo
    Config -->|"params for"| Core
    Config -->|"params for"| Plugins
    Examples -->|"uses messages"| Msg
    Scripts -->|"generates assets"| Models
    Datasets -->|"converts assets"| Models
    Utils -->|"helpers for"| Core
    Build -->|"builds"| Core
    Build -->|"builds"| Plugins
    Build -->|"builds"| Examples
    Build -->|"configures"| Scripts

    %% Click Events
    click Core "https://github.com/joao-borrego/grasp/tree/dev/grasp/"
    click Plugins "https://github.com/joao-borrego/grasp/tree/dev/plugins/"
    click Msg "https://github.com/joao-borrego/grasp/tree/dev/msgs/"
    click Models "https://github.com/joao-borrego/grasp/tree/dev/models/"
    click Worlds "https://github.com/joao-borrego/grasp/tree/dev/worlds/"
    click Config "https://github.com/joao-borrego/grasp/tree/dev/cfg/"
    click Examples "https://github.com/joao-borrego/grasp/tree/dev/examples/"
    click Scripts "https://github.com/joao-borrego/grasp/tree/dev/scripts/"
    click Datasets "https://github.com/joao-borrego/grasp/tree/dev/datasets/"
    click Utils "https://github.com/joao-borrego/grasp/tree/dev/utils/"
    click Cmake "https://github.com/joao-borrego/grasp/tree/dev/cmake/"
    click Deps "https://github.com/joao-borrego/grasp/blob/dev/deps/install_deps.sh"
    click Build "https://github.com/joao-borrego/grasp/blob/dev/CMakeLists.txt"

    %% Styles
    classDef sim fill:#dddddd,stroke:#555,stroke-width:1px
    classDef core fill:#cce5ff,stroke:#004085,stroke-width:1px
    classDef msg fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef asset fill:#fff3cd,stroke:#856404,stroke-width:1px
    classDef entry fill:#ffe5b4,stroke:#cc8400,stroke-width:1px
    classDef build fill:#f8d7da,stroke:#721c24,stroke-width:1px
```
