# provizio/provizio_dds architecture

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

- Interactive diagram: https://gitdiagram.com/provizio/provizio_dds
- Repository: https://github.com/provizio/provizio_dds

## Overview

##### Project Type and Purpose
- This is an open-source multi-language library (“provizio_dds”) providing a thin, high-level C++/Python API over eProsima Fast-DDS for real-time data distribution in robotics (Provizio products) and ROS2 interoperability. It also includes a point-cloud accumulation/fusion module in Python.

##### File‐Structure Analysis
- Top‐level build: CMakeLists.txt drives the C++ library build; setup.py and python/ folder drive the Python package.
- /provizio/dds: C++ headers for DomainParticipant, Publisher, Subscriber, QoS defaults, common utilities.
- src: core C++ implementations (e.g. domain_participant.cpp).
- python/: Python modules wrapping the C++ core (provizio_dds.py), plus utility modules (accumulation.py, gps_utils.py, point_cloud2.py), and __init__.py under inits for bootstrap.
- cache/, cmake/: build‐and‐dependency support.
- test/: C++ examples/tests (simplest_pub_sub, reliable_pub_sub, ROS interop) and Python test suite.
- .github/workflows: CI scripts for building C++ and Python packages and running tests.

##### Key Architectural Insights from README
- C++ and Python layers both expose:
- DomainParticipant factory
- Publisher<T> API
- Subscriber<T> API
- Built on top of eProsima Fast-DDS (linked as external project if not installed).
- Supports ROS2 message types (std_msgs, sensor_msgs) via IDL code generation.
- Python layer uses pip installation, bundles precompiled C++ extension modules.
- Accumulation module combines point‐cloud and localization topics into fused point clouds.

##### Components to Capture
A. Core C++ Layer
- Namespace provizio::dds
- DomainParticipant
- Publisher<T>
- Subscriber<T>
- qos_defaults, common utilities
- Underlying Fast-DDS (fastrtps, fastcdr)
B. Python Binding Layer
- provizio_dds Python extension (C++ binding via pybind11 or similar)
- Python modules: Publisher, Subscriber, QoS wrappers
- accumulation.DDSPointCloudsAccumulator
- utility modules (gps_utils, point_cloud2)
C. Build & Packaging
- CMake build orchestrator
- ExternalProject_Add for Fast-DDS if absent
- setup.py for Python packaging, pip install
D. External Dependencies
- eProsima Fast-DDS (network middleware)
- ROS2 message IDLs (std_msgs, sensor_msgs via provizio_dds_idls)
- libssl, C++14, Python3
E. User Applications & Tests
- C++ example executables (simplest_publisher, subscriber, reliable_pub_sub, ros_interop)
- Python scripts/tests (python_publisher, python_subscriber, accumulation_test)

##### Relationships & Data Flows
- User App → provizio_dds API (C++ or Python) → DomainParticipant → DDS Network
- Publisher API → serializes typed messages → Fast-DDS → wire
- Subscriber API ← deserializes messages from Fast-DDS → invokes user callback
- accumulation.DDSPointCloudsAccumulator: subscribes to multiple topics (point cloud, odometry) and produces fused data to client code
- Build Tools → drive compilation, code-generation, packaging

##### Architectural Patterns & Principles
- Layered abstraction: high-level provizio_dds API sits on top of Fast-DDS
- Adapter/Facade: uniform Publisher/Subscriber interface hiding DDS complexities
- Language bindings: single core C++ implementation with multi-language frontends (C++ API + Python wrappers)
- Automated build & CI pipelines ensure consistency across C++ and Python deliverables

##### Essential Elements
- Clear component names and interfaces
- Test clients as examples of usage

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Applications & Tests
    subgraph "User Applications & Tests"
        direction TB
        CppExamples["C++ Example/Test Clients"]:::user
        PyTests["Python Test Suite"]:::user
    end

    %% API Layers
    subgraph "provizio_dds C++ Core" 
        direction TB
        DomainParticipant["provizio::dds::DomainParticipant"]:::provizio
        Publisher["provizio::dds::Publisher<T>"]:::provizio
        Subscriber["provizio::dds::Subscriber<T>"]:::provizio
        QoSDefaults["provizio::dds::qos_defaults"]:::provizio
        CommonUtils["provizio::dds::common utilities"]:::provizio
    end

    subgraph "Python Binding Layer"
        direction TB
        PythonExt["provizio_dds Python Extension"]:::provizio
        PythonPubSub["provizio_dds.Publisher/Subscriber wrappers"]:::provizio
        Accumulator["accumulation.DDSPointCloudsAccumulator"]:::provizio
        GPSUtils["gps_utils"]:::provizio
        PointCloud2["point_cloud2"]:::provizio
        FastDDSInit["fastdds bootstrap init"]:::provizio
        ProvizioTypesInit["provizio_dds_python_types init"]:::provizio
    end

    %% External Dependencies
    subgraph "External Middleware & IDLs"
        direction TB
        FastDDS["eProsima Fast-DDS (fastrtps, fastcdr)"]:::external
        ROS2IDL["ROS2 Message IDLs (std_msgs, sensor_msgs)"]:::external
        Network["DDS Publish/Subscribe over UDP"]:::external
    end

    %% Build & Packaging
    subgraph "Build & Packaging"
        direction TB
        CMake["CMake Build Orchestrator"]:::build
        SetupPy["setup.py Python Packaging"]:::build
    end

    subgraph "CI Workflows"
        direction TB
        CI["GitHub Actions CI"]:::build
    end

    %% Connections
    CppExamples -->|"uses C++ API"| DomainParticipant
    CppExamples --> Publisher
    CppExamples --> Subscriber

    PyTests -->|"uses Python API"| PythonExt
    PyTests --> Accumulator

    DomainParticipant -->|"creates"| FastDDS
    Publisher -->|"serializes messages"| FastDDS
    Subscriber -->|"receives messages"| FastDDS
    FastDDS -->|"delivers to subscriber"| Subscriber
    FastDDS --> Network
    Network --> FastDDS
    Accumulator -->|"subscribes to topics"| FastDDS
    Accumulator -->|"outputs fused data"| PyTests

    CMake -->|"compiles"| DomainParticipant
    CMake --> Publisher
    CMake --> Subscriber
    CMake --> QoSDefaults
    CMake --> CommonUtils
    CMake --> PythonExt
    CMake --> FastDDSInit
    SetupPy -->|"bundles extension"| PythonExt
    SetupPy --> PythonPubSub

    CI --> CMake
    CI --> SetupPy
    CI --> PyTests
    CI --> CppExamples

    FastDDSInit --> FastDDS
    ProvizioTypesInit --> ROS2IDL
    DomainParticipant --> ProvizioTypesInit

    %% Click Events
    click DomainParticipant "https://github.com/provizio/provizio_dds/blob/develop/include/provizio/dds/domain_participant.h"
    click Publisher "https://github.com/provizio/provizio_dds/blob/develop/include/provizio/dds/publisher.h"
    click Subscriber "https://github.com/provizio/provizio_dds/blob/develop/include/provizio/dds/subscriber.h"
    click QoSDefaults "https://github.com/provizio/provizio_dds/blob/develop/include/provizio/dds/qos_defaults.h"
    click CommonUtils "https://github.com/provizio/provizio_dds/blob/develop/include/provizio/dds/common.h"
    click PythonExt "https://github.com/provizio/provizio_dds/blob/develop/python/provizio_dds.py"
    click Accumulator "https://github.com/provizio/provizio_dds/blob/develop/python/accumulation.py"
    click GPSUtils "https://github.com/provizio/provizio_dds/blob/develop/python/gps_utils.py"
    click PointCloud2 "https://github.com/provizio/provizio_dds/blob/develop/python/point_cloud2.py"
    click FastDDSInit "https://github.com/provizio/provizio_dds/blob/develop/python/inits/fastdds/__init__.py"
    click ProvizioTypesInit "https://github.com/provizio/provizio_dds/blob/develop/python/inits/provizio_dds_python_types/__init__.py"
    click CMake "https://github.com/provizio/provizio_dds/blob/develop/CMakeLists.txt"
    click SetupPy "https://github.com/provizio/provizio_dds/blob/develop/setup.py"
    click CI "https://github.com/provizio/provizio_dds/blob/develop/ .github/workflows/ci.yml"
    click CppExamples "https://github.com/provizio/provizio_dds/tree/develop/test/simplest_pub_sub"
    click PyTests "https://github.com/provizio/provizio_dds/tree/develop/test/python"

    %% Styles
    classDef provizio fill:#b8e986,stroke:#6aa11a,color:#000
    classDef external fill:#aed6f1,stroke:#2e75b6,color:#000
    classDef build fill:#d3d3d3,stroke:#7f7f7f,color:#000
    classDef user fill:#f9d5b0,stroke:#e07b39,color:#000
```
