# eclipse-ecal/ecal architecture

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

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

## Overview

##### Main Components
- eCAL Core Library: At the heart of the system, it implements both publish–subscribe and server–client communication. This includes modules for configuration, logging, monitoring, registration/discovery, and serialization (with support for protocols like Protobuf, Cap’n Proto, Flatbuffers, or plain strings).
- Transport Mechanisms: eCAL automatically chooses the best transport method—shared memory for local (ultra‐fast) communication and UDP/TCP for network communication.
- Language Interfaces and Bindings: The project supports multiple languages (C++, C, Python, C#, and even Rust, as indicated by community bindings). The directory structure includes separate language-specific subdirectories (e.g. lang/c, lang/csharp, lang/python) that contain these interfaces.
- Serialization Modules: Look for separate folders (such as “serialization/protobuf”, “serialization/flatbuffers”, “serialization/capnproto”, and “serialization/string”) that indicate how messages are serialized and deserialized.
- Build & Configuration: The project is heavily built around CMake (with several toolchain and helper modules) and includes multiple workflows and configuration files to support cross-platform builds (Windows, Ubuntu, macOS, etc).

##### Drill Down on the Relationships and Interactions
- Applications (or nodes) integrate with eCAL’s core API via their language-specific bindings. These API calls then send data to one of the internal transport layers.
- Within the core, the middleware decides whether to use a shared memory transport (for intra-node communication) or UDP/TCP (for inter-node communication).
- A discovery/registration mechanism (typically based on UDP multicast or similar techniques) ensures that publishers and subscribers as well as client–server pairs are aware of each other.
- The serialization modules bridge higher-level message definitions (Protobuf, Cap’n Proto, etc.) and the raw data transmission over the available transports.
- The ecosystem tools (Monitor, Recorder, Player, Sys) “listen in” on these data flows to enable debugging, recording, or system configuration adjustments without acting as brokers themselves.

##### Architectural Patterns and Design Principles
- Layered Architecture: The system’s design clearly separates the “application layer” (client code using language APIs) from the “communication core” (transport, serialization, registration) and from the “tooling layer.”
- Modular and Plugin Style: Each transport and serialization method is implemented as a module; this modularity allows easy integration of additional protocols and serialization mechanisms.
- Zero-Configuration / Brokerless: eCAL is designed to be “plug-and-play” – it automatically selects transports and discovers other nodes without external brokers.
- Cross-Platform & Extensible: Provided directories for numerous languages and a clear separation of build scripts (CMakeLists, presets, etc.) indicate that eCAL is engineered to support diverse environments and to be easily extended.

##### Relevant Technologies, Frameworks, and Tools
- CMake drives builds on multiple platforms.
- Technologies like HDF5 (for recording measurements) and various serialization frameworks such as Google Protobuf, Cap’n Proto, and Flatbuffers.
- Protocols such as shared memory, UDP, and TCP are integral.
- Language bindings for C/C++, Python, C#, etc. are a key facet.
- Tools for monitoring and debugging like eCAL Monitor.

##### Be Detailed and Accurate
– Ensure that key architectural elements such as the modular transport mechanism, serialization, discovery/registration, and tool integrations are clearly represented.
– Given the project’s large codebase (as seen from the extensive file tree), focus on conceptual modules rather than individual files.
– For example, group directories by their functionality: “core,” “serialization,” “lang,” “tools” and “thirdparty.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer: User Applications / Language Bindings
    subgraph "User Applications/Language Bindings"
        lang_c("C++ (lang/c)"):::language
        lang_cs("C# (lang/csharp)"):::language
        lang_py("Python (lang/python)"):::language
    end

    %% Middle Layer: eCAL Core
    subgraph "eCAL Core"
        CoreAPI("eCAL Core API\n(Pub/Sub,Client/Server)"):::core
        Discovery("Discovery/Registration"):::core

        subgraph "Transport Mechanisms"
            shm("Shared Memory Transport"):::transport
            udp("UDP/TCP Transport"):::transport
        end

        subgraph "Serialization Modules"
            proto("Protobuf"):::serialization
            flat("Flatbuffers"):::serialization
            capn("Cap'n Proto"):::serialization
            str_ser("String Serialization"):::serialization
        end
    end

    %% Build & Configuration
    subgraph "Build & Configuration"
        cmake_file("CMakeLists.txt"):::build
        cmake_mod("cmake/Modules"):::build
    end

    %% Bottom Layer: Utility/Tooling Components
    subgraph "Utility/Tooling Components"
        monitor("Monitor"):::tools
        recorder("Recorder"):::tools
        player("Player"):::tools
        sys("Sys"):::tools
    end

    %% Connections
    lang_c -->|"calls"| CoreAPI
    lang_cs -->|"calls"| CoreAPI
    lang_py -->|"calls"| CoreAPI

    CoreAPI -->|"uses"| Discovery
    CoreAPI -->|"selects"| shm
    CoreAPI -->|"selects"| udp
    CoreAPI -->|"bridges"| proto
    CoreAPI -->|"bridges"| flat
    CoreAPI -->|"bridges"| capn
    CoreAPI -->|"bridges"| str_ser

    Discovery -->|"informs"| shm
    Discovery -->|"informs"| udp

    shm -->|"feeds"| monitor
    shm -->|"feeds"| recorder
    shm -->|"feeds"| player
    shm -->|"feeds"| sys

    udp -->|"feeds"| monitor
    udp -->|"feeds"| recorder
    udp -->|"feeds"| player
    udp -->|"feeds"| sys

    cmake_file -->|"builds"| CoreAPI
    cmake_mod -->|"builds"| CoreAPI

    %% Click Events
    click CoreAPI "https://github.com/eclipse-ecal/ecal/tree/master/ecal/core"
    click shm "https://github.com/eclipse-ecal/ecal/tree/master/ecal/core/src/io/shm"
    click udp "https://github.com/eclipse-ecal/ecal/tree/master/ecal/core/src/io/udp"
    click lang_c "https://github.com/eclipse-ecal/ecal/tree/master/lang/c"
    click lang_cs "https://github.com/eclipse-ecal/ecal/tree/master/lang/csharp"
    click lang_py "https://github.com/eclipse-ecal/ecal/tree/master/lang/python"
    click proto "https://github.com/eclipse-ecal/ecal/tree/master/serialization/protobuf"
    click flat "https://github.com/eclipse-ecal/ecal/tree/master/serialization/flatbuffers"
    click capn "https://github.com/eclipse-ecal/ecal/tree/master/serialization/capnproto"
    click str_ser "https://github.com/eclipse-ecal/ecal/tree/master/serialization/string"
    click monitor "https://github.com/eclipse-ecal/ecal/tree/master/app/mon"
    click recorder "https://github.com/eclipse-ecal/ecal/tree/master/app/rec"
    click player "https://github.com/eclipse-ecal/ecal/tree/master/app/play"
    click sys "https://github.com/eclipse-ecal/ecal/tree/master/app/sys"
    click cmake_file "https://github.com/eclipse-ecal/ecal/blob/master/CMakeLists.txt"
    click cmake_mod "https://github.com/eclipse-ecal/ecal/tree/master/cmake/Modules"

    %% Styles
    classDef language fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef core fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef transport fill:#FFA07A,stroke:#000,stroke-width:1px;
    classDef serialization fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef tools fill:#D3D3D3,stroke:#000,stroke-width:1px;
    classDef build fill:#FFFF99,stroke:#000,stroke-width:1px;
```
