# eclipse-cyclonedds/cyclonedds architecture

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

- Interactive diagram: https://gitdiagram.com/eclipse-cyclonedds/cyclonedds
- Repository: https://github.com/eclipse-cyclonedds/cyclonedds

## Overview

##### Project type and purpose
- Project type: an open-source, standards-compliant implementation of the OMG DDS (Data Distribution Service) publish-subscribe middleware, delivered as a C library with optional C++ and Python language bindings, an IDL compiler, performance tools, fuzz/test suites, and plugin-based extensibility (security, shared-memory, etc.).
- Purpose: provide zero-configuration discovery, efficient serialization, reliable/unreliable pub/sub messaging over RTPS, pluggable security modules, shared-memory fast paths, and tooling for IDL processing, performance measurement, and diagnostics.

##### File structure (highlights)
- src/ddsrt – the low-level runtime library for portability (threads, sockets, atomics, memory, logging)
- src/core/ddsc – the core DDS API, entity management (DomainParticipants, Publishers, Subscribers, Topics, DataWriters/DataReaders)
- src/core/ddsi – the RTPS network protocol implementation (discovery, message framing, reliability, transport)
- src/core/cdr – serialization (XCDR1/2) support
- src/idl – IDL compiler (parser + code generator) and type metadata
- src/security – core security FSM and builtin plugins (access control, authentication, cryptography), OpenSSL hooks
- src/psmx_iox – PSMX plugins for zero-copy shared-memory (Iceoryx)
- src/tools – CLI tools: idlpp, idlc, ddsperf, sanity scripts
- examples, fuzz, tests – usage examples, fuzz targets, unit & integration tests
- etc/cyclonedds.xsd, docs/manual/config – runtime configuration schema & docs
- CMakeLists, azure-pipelines, GitHub workflows – build/test automation

##### README insights
- Core components listed under “DCPS”, “DDS Security”, “DDSI-RTPS”, etc.
- References to three layers: API (C/C++/Python), core, network
- Configuration via XML (CYCLONEDDS_URI)
- Plugin architecture for security and PSMX

1. Application layer (your DDS application code – DomainParticipant, Topics, DW/DR)
2. Language bindings: C API (ddsc), C++ wrapper, Python wrapper
3. Core middleware:
– ddsrt (runtime services)
– cdr (serialization)
– idl compiler (build-time)
– idl metadata / XTypes (type system)
4. RTPS network layer (ddsi): discovery, message exchange over UDP/TCP
5. Plugin framework:
– Security core + builtin_plugins + OpenSSL plugin
– PSMX core + Iceoryx plugin
6. Tools & examples (idlpp, idlc, ddsperf)
7. Build/test infrastructure (CMake, CI pipelines, fuzz targets)
8. Configuration subsystem (XML schema, environment variable)
– Application → C API → core ddsc → serialization (cdr)
– core ddsc ↔ ddsi (invoke discovery, send/receive RTPS messages)
– ddsi → OS network stack (UDP/TCP sockets)
– core ddsc → ddsrt (threading, memory, logging)
– Plugin loader (at startup): security & PSMX plugins register via core hooks
– Tools & IDL compiler run at build time → generate code → linked into application
– Configuration: loaded by core on startup → influences discovery, QoS, transports
c. Architectural patterns & principles:
– Layered architecture (API → core → network → OS)
– Plugin/extension points (security, PSMX)
– Separation of concerns (serialization vs. networking vs. entity management)
– Build-time code generation (IDL → type support)
– Test harnesses & fuzzing decoupled via CMake targets
d. Key technologies & frameworks:
– CMake for build & packaging
– C/C++ (ISO C99 + modern C++)
– OpenSSL for security plugin
– Iceoryx (optional) for shared memory plugin
– Bison/Flex (cached) for IDL parser
– CTest, UCUnit, custom fuzz scripts for testing

##### Essential elements to capture
– Layer separation (API | Core | Network | OS)
– Plugin architecture (security, PSMX)
– Build vs. run-time components
– Configuration input path to the core
– Tools & test harness side-car

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "Application & Language Bindings"
        direction TB
        App["DDS Application\n(DomainParticipant, DataWriters/Readers)"]:::app
        C_API["C API (ddsc)"]:::lang
        CPP_API["C++ Wrapper"]:::lang
        PY_API["Python Wrapper"]:::lang
    end

    subgraph "Core Middleware"
        direction TB
        ddsrt["ddsrt\n(Runtime Services)"]:::core
        cdr["cdr\n(Serialization XCDR1/2)"]:::core
        ddsc["Core DDS API\n(Entity Management)"]:::core
        ddsi["ddsi\n(RTPS Transport & Discovery)"]:::core
        idl["IDL Compiler & Type Metadata"]:::build
        sec_core["Security Core\n(FSM & Plugin Framework)"]:::plugin
        sec_builtin["Security Built-In Plugins"]:::plugin
        sec_ssl["OpenSSL Security Plugin"]:::plugin
        psmx["PSMX Shared-Memory Plugin\n(Iceoryx)"]:::plugin
    end

    subgraph "Tools & Test Harnesses"
        direction TB
        idlpp["IDL Preprocessor\n(idlpp)"]:::tool
        idlc["IDL Compiler Frontend\n(idlc)"]:::tool
        ddsperf["Performance Tool\n(ddsperf)"]:::tool
        confgen["Configuration Generator\n(_confgen)"]:::tool
        examples["Examples"]:::examples
        fuzz["Fuzz Targets"]:::tests
        tests["Unit & Integration Tests"]:::tests
    end

    subgraph "Network & OS"
        direction TB
        OS_NET["OS Network Stack\n(UDP/TCP)"]:::external
        Config["Configuration\n(XML schema & docs)"]:::external
        CI["Build & CI Automation"]:::external
    end

    %% Runtime Flows
    App -->|"uses"| C_API
    C_API -->|"entity mgmt"| ddsc
    ddsc -->|"serialization"| cdr
    ddsc -->|"runtime services"| ddsrt
    ddsc -->|"transport API"| ddsi
    ddsi -->|"sockets"| OS_NET
    sec_core -->|"loads plugins"| sec_builtin
    sec_core -->|"loads plugin"| sec_ssl
    sec_core -->|"loads plugin"| psmx

    ddsc -->|"plugin hooks"| sec_core
    ddsc -->|"plugin hooks"| psmx

    %% Build-time Flows
    idlpp -.->|"preprocess IDL"| idlc
    idlc -.->|"generate code"| idl
    idl -.->|"generated types"| App

    CI -.->|build/test| idlpp
    CI -.->|build/test| idlc
    CI -.->|build/test| ddsperf
    CI -.->|run| tests
    CI -.->|run| fuzz

    %% Configuration Flow
    Config -->|"load on startup"| ddsc
    Config -->|"load on startup"| ddsi

    %% Tools & Examples depend on Core
    App -->|“demo & sample”| examples
    App -->|“performance”| ddsperf

    %% Click Events
    click ddsrt "https://github.com/eclipse-cyclonedds/cyclonedds/tree/master/src/ddsrt"
    click ddsc "https://github.com/eclipse-cyclonedds/cyclonedds/tree/master/src/core/ddsc"
    click ddsi "https://github.com/eclipse-cyclonedds/cyclonedds/tree/master/src/core/ddsi"
    click cdr "https://github.com/eclipse-cyclonedds/cyclonedds/tree/master/src/core/cdr"
    click idl "https://github.com/eclipse-cyclonedds/cyclonedds/tree/master/src/idl"
    click sec_core "https://github.com/eclipse-cyclonedds/cyclonedds/tree/master/src/security/core"
    click sec_builtin "https://github.com/eclipse-cyclonedds/cyclonedds/tree/master/src/security/builtin_plugins"
    click sec_ssl "https://github.com/eclipse-cyclonedds/cyclonedds/tree/master/src/security/openssl"
    click psmx "https://github.com/eclipse-cyclonedds/cyclonedds/tree/master/src/psmx_iox"
    click idlpp "https://github.com/eclipse-cyclonedds/cyclonedds/tree/master/src/tools/idlpp"
    click idlc "https://github.com/eclipse-cyclonedds/cyclonedds/tree/master/src/tools/idlc"
    click ddsperf "https://github.com/eclipse-cyclonedds/cyclonedds/tree/master/src/tools/ddsperf"
    click confgen "https://github.com/eclipse-cyclonedds/cyclonedds/tree/master/src/tools/_confgen"
    click examples "https://github.com/eclipse-cyclonedds/cyclonedds/tree/master/examples"
    click fuzz "https://github.com/eclipse-cyclonedds/cyclonedds/tree/master/fuzz"

    %% Styles
    classDef app fill:#eef,stroke:#339,stroke-width:1px
    classDef lang fill:#efe,stroke:#393,stroke-width:1px
    classDef core fill:#def,stroke:#236,stroke-width:1px
    classDef plugin fill:#fed,stroke:#d63,stroke-width:1px,stroke-dasharray: 5 5
    classDef build fill:#fdd,stroke:#933,stroke-width:1px,stroke-dasharray: 3 3
    classDef tool fill:#ffd,stroke:#aa0,stroke-width:1px
    classDef tests fill:#fdf,stroke:#939,stroke-width:1px,stroke-dasharray: 2 2
    classDef examples fill:#dfd,stroke:#393,stroke-width:1px
    classDef external fill:#eee,stroke:#666,stroke-width:1px,stroke-dasharray: 4 2
```
