# Integrate flunder into your app

## Blueprint: Integrating with the FLECS Service Mesh using `flunder` (C++)

### Introduction

This documentation serves as a **blueprint** for developers looking to integrate their applications with the **FLECS Service Mesh**, a real-time communication layer powered by the open-source protocol **Zenoh**. The example provided demonstrates how to use the `flunder` C++ client to set up a high-performance pub/sub communication pattern.

You can use this example as a **starting point** for developing your own low-latency, service-mesh-aware applications.

***

### Goals of the Blueprint

* Show how to **initialize and configure** a `flunder` client.
* Provide reusable **callback mechanisms** for processing messages.
* Illustrate how to **subscribe to and publish** structured messages.
* Highlight performance-related practices such as **timestamp-based latency analysis**.
* Serve as a **template for production-grade implementations** using C++.

***

### Key Features

* ✅ Real-time messaging using `flunder` over Zenoh
* ✅ Strong typing and parsing logic for message payloads
* ✅ Timestamp-based performance metrics
* ✅ User-defined context (e.g., tagging) in callbacks
* ✅ Clean shutdown support

***

### How to Use This Blueprint

#### 1. Clone and Review the Example

Start by inspecting the [example source](https://github.com/FLECS-Technologies/flunder/tree/main/examples) in the `flunder` repository.

#### 2. Understand the Components

**a. Client Initialization and Connection**

```cpp
auto flunder_client = flunder::client_t{};
flunder_client.connect();
flunder_client.add_mem_storage("flunder-cpp", "flecs/flunder/**");
```

Use this pattern to:

* Instantiate a `flunder` client
* Connect it to the mesh
* Add optional in-memory storage (for local caching)

**b. Subscribing to Topics**

```cpp
flunder_client.subscribe("flecs/flunder/cpp/**", &flunder_receive_callback);
```

Topics follow a hierarchical format and support wildcards. The callback processes incoming messages by topic name.

If you need user context in your callbacks (e.g., tags, identifiers):

```cpp
const char* userdata = "Hello, world!";
flunder_client.subscribe("flecs/flunder/external", &flunder_receive_callback_userp, userdata);
```

**c. Publishing Data**

```cpp
flunder_client.publish("flecs/flunder/cpp/int", 1234);
```

Repeat as needed for different data types (e.g., `double`, `string`, timestamps).

**d. Measuring Latency (Optional)**

```cpp
const auto t = std::chrono::high_resolution_clock::now().time_since_epoch().count();
flunder_client.publish("flecs/flunder/cpp/timestamp", t);
```

On the receiving side, subtract this timestamp from the current time to get one-way latency estimates.

***

### Extend This Blueprint

You can build on this example to:

* Subscribe to more topic patterns using semantic names (e.g., `sensor/temperature`, `status/health`)
* Add authentication or security layers
* Swap in persistent storage instead of `add_mem_storage`
* Integrate with other systems (e.g., OPC UA, MQTT) via adapters

***

### Performance Insights

Our internal benchmarks show latencies as low as **35–45µs**, depending on the transport and host system. This makes `flunder` an ideal fit for industrial and time-sensitive workloads.

For a detailed benchmark comparison (vs. MQTT, OPC UA, ZeroMQ, etc.), please [contact us](https://flecs.tech/ressources/contact/) to request the whitepaper.

***

### Getting Started

#### Build the Example

```bash
g++ -std=c++17 -o flunder_example example.cpp -lflunder -lpthread
```

#### Run

```bash
./flunder_example
```

Terminate with `Ctrl+C`.

***

### Next Steps

Use this example as a **template**, and start replacing topic names, data structures, and business logic with your own. If you’re building automation systems, digital twins, real-time analytics, or other data-driven applications, this blueprint is your launchpad into the FLECS ecosystem.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flecs.tech/product-docs/engineering/service-mesh/integrate-flunder-into-your-app.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.