# eclipse-iceoryx/iceoryx2 architecture

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

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

## Overview

##### Project type and purpose
- iceoryx2 is a monorepo for a zero-copy, lock-free, service-oriented IPC middleware.
- It provides a Rust core engine plus pluggable language bindings (C, C++, Python), platform-abstraction layers, tools (CLI, tunnel, services), examples and benchmarks.

##### Top-level architectural components
- Rust Core Engine (“iceoryx2”)
– Manages ports, chunks, samples, connections, service builders (publish-subscribe, request-response, event).
- Platform Abstraction Layer (“iceoryx2-pal”)
– Concurrency primitives (mutex, barrier, semaphore), OS API wrappers (posix, linux, macOS, QNX, Windows), configuration, testing hooks.
- Core Utility Crates
– Container and lock-free data structures (iceoryx2-bb/container, lock-free, elementary-traits, memory).
– Conformance test macros and trait tests.
- Communication Abstraction Layer (“iceoryx2-cal”)
– Policy-driven implementations for shared memory, sockets, zero-copy connections, dynamic/static storage, event signalers.
- Language Bindings
– C API wrapper (iceoryx2-c) generated via cbindgen.
– C++ API (iceoryx2-cxx) consuming core C API and offering RAII, error types, service builders.
– Python extension (iceoryx2-ffi/python) via PyO3, mapping Rust core to Python idioms.
- CLI Tools (iceoryx2-cli)
– Subcommands: iox2-config, iox2-node, iox2-service, iox2-tunnel. Uses core crates for configuration, filtering, output.
- Service Discovery Services (iceoryx2-services/discovery)
– A library offering service registration, lookup, tracking for dynamic topologies.
- Tunnel Framework (iceoryx2-tunnel)
– Backend traits, transport implementations, end-to-end tests, zenoh bridge.
- Userland Utilities (iceoryx2-userland/record-and-replay)
– Record and replay library and tools.
- Examples & Benchmarks
– Multi-language examples demonstrating each messaging pattern.
– Benchmarks for mechanism and architecture performance.
- Documentation, CI, Build Scripts
– Doxygen, Sphinx, Bazel and CMake build configs, GitHub workflows, internal scripts.

##### Relationships and data-flow
- Core Engine ←─ depends on ── PAL crates, utility crates, CAL
- C API → wraps → Core Engine
- C++ API → consumes → C API + Core Engine types
- Python API → binds → Core Engine via FFI
- CLI Tools → link → CLI library → use → Core Engine & Bindings
- Service Discovery → library → uses → Core Engine ports & samples
- Tunnel → implements → discovery & relay → uses → Core Engine ports
- Record-&-Replay → side-channel → uses → Core Engine’s serialization
- Examples & Benchmarks → client apps → use → Bindings & Core Engine

##### Architectural patterns
- Modular crate-per-component, using Cargo + Bazel as a polyglot build system.
- Service-Oriented Architecture: services expose ports, use builders.
- Policy pattern in CAL: pluggable implementations selected at compile time.
- Layered binding pattern: Rust core → C API → C++/Python consumers.
- Tunnel and CLI use adapter pattern to integrate with core IPC.

##### Essential elements to capture
- Core Engine internal modules: port management, service builder, sample life-cycle.
- PAL providing OS primitives.
- CAL policy plug-ins (shared memory, sockets, dynamic/static storage).
- Language layering: C API sits atop Core, then C++/Python libraries.
- High-level tools (CLI, Tunnel, Service Discovery) as clients of Core and Bindings.
- Example applications as users of the public API.
- Build system integration: Bazel and Cargo, but keep build nuance in a side annotation.

##### Final advice
- How data flows from publisher to subscriber (shared memory buffer → port → sample → callback).
- Zero-copy and lock-free nature by annotating the shared memory and PAL layer.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Core Layer"
        CoreEngine["Rust Core Engine"]:::core
    end

    subgraph "Platform Abstraction Layer"
        PAL["iceoryx2-pal"]:::pal
    end

    subgraph "Core Utility Crates"
        Container["container"]:::util
        LockFree["lock-free"]:::util
        ElemTraits["elementary-traits"]:::util
        Memory["memory"]:::util
        Conformance["conformance-test-macros"]:::util
        Derive["derive-macros"]:::util
        TraitTests["trait-tests"]:::util
    end

    subgraph "Communication Abstraction Layer"
        CAL["iceoryx2-cal"]:::cal
    end

    subgraph "Language Bindings"
        CAPI["C API (iceoryx2-c)"]:::bind
        CPPAPI["C++ API (iceoryx2-cxx)"]:::bind
        PythonAPI["Python FFI"]:::bind
    end

    subgraph "Tools & Services"
        CLI["CLI Tools"]:::tools
        ServiceDisc["Service Discovery"]:::services
        Tunnel["Tunnel Framework"]:::services
        RecordReplay["Record & Replay"]:::services
    end

    subgraph "Examples & Benchmarks"
        Examples["Examples"]:::examples
        Benchmarks["Benchmarks"]:::examples
    end

    subgraph "Documentation & CI"
        Doc["Documentation"]:::build
        Bazel["Bazel Config"]:::build
        CMake["CMake Config"]:::build
        CI["CI Workflows"]:::build
    end

    PAL -->|"uses"| CoreEngine
    Container -->|"utility"| CoreEngine
    LockFree -->|"lock-free primitives"| CoreEngine
    ElemTraits -->|"traits"| CoreEngine
    Memory -->|"memory allocators"| CoreEngine
    Conformance -->|"test macros"| CoreEngine
    Derive -->|"derive macros"| CoreEngine
    TraitTests -->|"trait tests"| CoreEngine
    CAL -->|"policy plug-ins"| CoreEngine

    CAPI -->|"cbindgen FFI"| CoreEngine
    CPPAPI -->|"C++ wrapper"| CAPI
    PythonAPI -->|"PyO3 extension"| CoreEngine

    CLI -->|"links & uses"| CoreEngine
    CLI -->|"links"| CAPI
    ServiceDisc -->|"uses ports/samples"| CoreEngine
    Tunnel -->|"uses ports & relay"| CoreEngine
    RecordReplay -->|"uses serialization"| CoreEngine

    Examples -->|"client uses"| CAPI
    Examples -->|"client uses"| CPPAPI
    Examples -->|"client uses"| PythonAPI
    Benchmarks -->|"measures"| CoreEngine

    Doc --- Bazel
    Doc --- CMake
    Doc --- CI

    click CoreEngine "https://github.com/eclipse-iceoryx/iceoryx2/tree/main/iceoryx2/"
    click PAL "https://github.com/eclipse-iceoryx/iceoryx2/tree/main/iceoryx2-pal/"
    click Container "https://github.com/eclipse-iceoryx/iceoryx2/tree/main/iceoryx2-bb/container/"
    click LockFree "https://github.com/eclipse-iceoryx/iceoryx2/tree/main/iceoryx2-bb/lock-free/"
    click ElemTraits "https://github.com/eclipse-iceoryx/iceoryx2/tree/main/iceoryx2-bb/elementary-traits/"
    click Memory "https://github.com/eclipse-iceoryx/iceoryx2/tree/main/iceoryx2-bb/memory/"
    click Conformance "https://github.com/eclipse-iceoryx/iceoryx2/tree/main/iceoryx2-bb/conformance-test-macros/"
    click Derive "https://github.com/eclipse-iceoryx/iceoryx2/tree/main/iceoryx2-bb/derive-macros/"
    click TraitTests "https://github.com/eclipse-iceoryx/iceoryx2/tree/main/iceoryx2-bb/trait-tests/"
    click CAL "https://github.com/eclipse-iceoryx/iceoryx2/tree/main/iceoryx2-cal/"
    click CAPI "https://github.com/eclipse-iceoryx/iceoryx2/tree/main/iceoryx2-c/"
    click CPPAPI "https://github.com/eclipse-iceoryx/iceoryx2/tree/main/iceoryx2-cxx/"
    click PythonAPI "https://github.com/eclipse-iceoryx/iceoryx2/tree/main/iceoryx2-ffi/python/"
    click CLI "https://github.com/eclipse-iceoryx/iceoryx2/tree/main/iceoryx2-cli/"
    click ServiceDisc "https://github.com/eclipse-iceoryx/iceoryx2/tree/main/iceoryx2-services/discovery/"
    click Tunnel "https://github.com/eclipse-iceoryx/iceoryx2/tree/main/iceoryx2-tunnel/"
    click RecordReplay "https://github.com/eclipse-iceoryx/iceoryx2/tree/main/iceoryx2-userland/record-and-replay/src/"
    click Examples "https://github.com/eclipse-iceoryx/iceoryx2/tree/main/examples/"
    click Benchmarks "https://github.com/eclipse-iceoryx/iceoryx2/tree/main/benchmarks/"
    click Doc "https://github.com/eclipse-iceoryx/iceoryx2/tree/main/doc/"
    click Bazel "https://github.com/eclipse-iceoryx/iceoryx2/blob/main/WORKSPACE.bazel"
    click CMake "https://github.com/eclipse-iceoryx/iceoryx2/blob/main/CMakeLists.txt"
    click CI "https://github.com/eclipse-iceoryx/iceoryx2/tree/main/.github/workflows/"

    classDef core fill:#2196f3,stroke:#000,color:#fff
    classDef pal fill:#9e9e9e,stroke:#000,color:#fff
    classDef util fill:#64b5f6,stroke:#000,color:#000
    classDef cal fill:#009688,stroke:#000,color:#fff
    classDef bind fill:#4caf50,stroke:#000,color:#fff
    classDef tools fill:#ff9800,stroke:#000,color:#000
    classDef services fill:#9c27b0,stroke:#000,color:#fff
    classDef examples fill:#ffeb3b,stroke:#000,color:#000
    classDef build fill:#cfd8dc,stroke:#000,color:#000
```
