# wirepas/wirepas-mqtt-library architecture

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

- Interactive diagram: https://gitdiagram.com/wirepas/wirepas-mqtt-library
- Repository: https://github.com/wirepas/wirepas-mqtt-library

## Overview

##### Project type and purpose
- This is an open-source Python library (wheel) named “wirepas-mqtt-library.”
- Its purpose is to wrap MQTT connectivity and protobuf payload handling for the Wirepas Gateway backend API.
- It provides both synchronous and asynchronous methods to control a full Wirepas network without managing individual gateway connections.

##### File structure
- Top-level directories:
- .github – CI workflows for packaging and documentation
- docs – Sphinx documentation sources and build scripts
- examples – Python scripts demonstrating library usage
- wirepas_mqtt_library – the actual Python module implementing:
– __about__.py (metadata)
– wirepas_network_interface.py (core interface)
– topic_helper.py (topic naming/management)
– wirepas_otap_helper.py, wirepas_tlv_app_config_helper.py (feature helpers)
– otap_status_storage.py (state persistence)
- Configuration files:
- requirements.txt, setup.py for packaging dependencies
- docs/conf.py for Sphinx
- The structure follows a typical library layout, separating documentation, examples, and source code.

##### README for additional insights
- Describes a three–threading model:
- Network thread runs all internal MQTT operations
- Worker thread(s) dispatch user callbacks (configurable pool size)
- Calling thread blocks on synchronous calls
- Emphasizes synchronous vs. asynchronous usage patterns
- Notes use of MQTT with protobuf payloads under the hood

a. Components
1. User Application (example scripts or client code)
2. WirepasNetworkInterface (WN I) – the library’s façade
3. MQTT Client Library (e.g., paho-mqtt)
4. MQTT Broker (Wirepas Gateway endpoint)
5. Wirepas Gateway / Network Backend
6. Protobuf Encoder/Decoder inside the library
7. Threading subsystem:
– Network Thread
– Worker Thread Pool
– Calling Thread
8. Helper modules: topic_helper, OTAP helper, TLV app config helper, status storage
b. Relationships / Data flow
- User Application calls WNI methods (sync or async).
- WNI hands off publish/subscribes to the MQTT client on the Network Thread.
- MQTT Broker ↔ WNI via MQTT topics (protobuf payloads).
- Incoming MQTT messages go to the Network Thread → parsed by Protobuf Decoder → dispatched to Worker Thread(s).
- Worker threads execute user callbacks or resolve futures for synchronous calls.
- Helpers manage topic naming, OTAP sequences, TLV config serialization, and store OTAP status.
c. Architectural patterns / principles
- Pub/Sub messaging via MQTT
- Thread-based concurrency to isolate network IO from user callbacks
- Modular helpers for cross-cutting concerns (topics, OTAP, config)
- Dual sync/async API design for flexibility
d. Key technologies
- Python 3.x
- MQTT (via paho-mqtt or similar client)
- Protocol Buffers for payload serialization
- Sphinx for docs
- Threading module for concurrency

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Calling Thread
    subgraph "Calling Thread" 
        direction TB
        UserApp["User Application"]:::user
        CallingBlock["Blocks on synchronous calls"]:::thread
    end

    %% Library Core
    subgraph "Wirepas MQTT Library"
        direction TB
        WNI["WirepasNetworkInterface"]:::library
        Proto["Protobuf Encoder/Decoder"]:::library
        Topic["Topic Helper"]:::helper
        OTAP["OTAP Helper"]:::helper
        TLV["TLV App Config Helper"]:::helper
        Status["OTAP Status Storage"]:::helper
        Meta["__about__.py"]:::config
    end

    %% Network Thread & MQTT
    subgraph "Network Thread"
        direction TB
        MQTTClient["MQTT Client (paho-mqtt)"]:::library
    end

    Broker["MQTT Broker"]:::external
    Backend["Wirepas Gateway Backend"]:::external

    %% Worker Thread Pool
    subgraph "Worker Thread Pool"
        direction TB
        Worker["Worker Threads"]:::thread
    end

    %% Project Configuration
    subgraph "Project Configuration"
        direction TB
        DocsSrc["docs/wirepas_mqtt_library.rst"]:::docs
        SphinxConf["docs/conf.py"]:::docs
        Setup["setup.py"]:::config
        Req["requirements.txt"]:::config
        CI1[".github/workflows/python-package.yml"]:::config
        CI2[".github/workflows/sphinx.yml"]:::config
    end

    %% Connections
    UserApp -->|"calls sync/async methods"| WNI
    WNI --> Proto
    WNI --> Topic
    WNI --> OTAP
    WNI --> TLV
    WNI --> Status
    WNI -->|"publish/subscribe"| MQTTClient
    MQTTClient -->|"MQTT pub/sub"| Broker
    Broker -->|"forwards to"| Backend
    Broker -->|"incoming messages"| MQTTClient
    MQTTClient --> Proto
    Proto -->|"decoded messages"| Worker
    Worker -->|"executes callbacks or resolves futures"| UserApp

    %% Click Events
    click UserApp "https://github.com/wirepas/wirepas-mqtt-library/tree/main/examples/"
    click WNI "https://github.com/wirepas/wirepas-mqtt-library/blob/main/wirepas_mqtt_library/wirepas_network_interface.py"
    click Proto "https://github.com/wirepas/wirepas-mqtt-library/blob/main/wirepas_mqtt_library/wirepas_network_interface.py"
    click Topic "https://github.com/wirepas/wirepas-mqtt-library/blob/main/wirepas_mqtt_library/topic_helper.py"
    click OTAP "https://github.com/wirepas/wirepas-mqtt-library/blob/main/wirepas_mqtt_library/wirepas_otap_helper.py"
    click TLV "https://github.com/wirepas/wirepas-mqtt-library/blob/main/wirepas_mqtt_library/wirepas_tlv_app_config_helper.py"
    click Status "https://github.com/wirepas/wirepas-mqtt-library/blob/main/wirepas_mqtt_library/otap_status_storage.py"
    click Meta "https://github.com/wirepas/wirepas-mqtt-library/blob/main/wirepas_mqtt_library/__about__.py"
    click DocsSrc "https://github.com/wirepas/wirepas-mqtt-library/blob/main/docs/wirepas_mqtt_library.rst"
    click SphinxConf "https://github.com/wirepas/wirepas-mqtt-library/blob/main/docs/conf.py"
    click Setup "https://github.com/wirepas/wirepas-mqtt-library/blob/main/setup.py"
    click Req "https://github.com/wirepas/wirepas-mqtt-library/blob/main/requirements.txt"
    click CI1 "https://github.com/wirepas/wirepas-mqtt-library/blob/main/.github/workflows/python-package.yml"
    click CI2 "https://github.com/wirepas/wirepas-mqtt-library/blob/main/.github/workflows/sphinx.yml"

    %% Styles
    classDef external fill:#f9d,stroke:#333;
    classDef library fill:#bbf,stroke:#333;
    classDef helper fill:#bfb,stroke:#333;
    classDef thread fill:#ffb,stroke:#333;
    classDef user fill:#ffd,stroke:#333;
    classDef config fill:#eee,stroke:#333;
    classDef docs fill:#fbf,stroke:#333;
```
