Documentation Center

relayr Cloud Architecture Diagram

The diagram below illustrates the architecture of the relayr Cloud and the flow of data to and from users and devices:

relayr Cloud Architecture Diagram

To summarize: Devices transmit and receive data to and from the Cloud through one or more application protocols (e.g., MQTT and Websockets). The data is passed through the MQTT Broker, which uses the Data Router to ensure that the data is delivered to the proper recipients, such as the data store and services that subscribe to that device’s data. Cloud users can access the Cloud directly through the HTTP API or through the Developer Dashboard, which provides an interface for accessing device data and services.

External Entities

The following entities reside outside of the Cloud and use one or more application protocols to connect and interface with it:


A user is an individual or an external application who is using the relayr platform.


Devices constitute the most basic element of the relayr platform. A device is an entity that can transmit and receive data to and from the Cloud. As shown in the diagram, devices can connect to the Cloud through MQTT and Websockets. However, in a fog architecture setup, devices can also connect through the Edge Agent.

Click here to learn more about devices.

Developer Dashboard

The Developer Dashboard is the user interface of the relayr Cloud. It provides a visual interface for managing devices and accessing device data.

Click here to go to our Getting Started tutorial series for the Developer Dashboard.

Edge Agent

The Edge Agent is relayr’s fog architecture software. It runs on an IoT gateway and manages the traffic between the devices connected to the gateway and the relayr platform. Is primarily used in environments where there is the need to interface with legacy protocols — Modbus, Profibus, BACnet, etc — and/or where there is low connectivity. Devices connect directly to the Edge Agent, which transmits their data through one of the uplink protocols described below.

Click here to learn more about the Edge Agent.

Application Protocols

Application protocols facilitate the connection between clients (users, devices, the Dashboard) and the Cloud.


relayr’s HTTP API provides programmatic access to all of the resources and services in the relayr Cloud. When a user or application makes a call to the API to execute a command or return a resource, the call is routed to the correct endpoint or service through the HTTP router, and then the desired action is performed.

Click here to go to the full API reference.


MQTT is an industry-standard lightweight application protocol that uses a pub/sub messaging pattern. It is currently the primary application protocol used by the relayr Cloud for device data transmission.


The relayr Cloud also supports Websockets, an HTML5-based communication protocol designed to reduce the strain on servers while enabling data streaming.

The Edge Agent handles device data aggregation locally and then forwards it to the Cloud through one of its secure uplinks. The regular Edge Agent Uplink uploads device data in real-time, while the Batch Uplink uploads data in batches. Once the data is uploaded through the secure uplink, it is passed to the Data Router in the same way as data from non-Edge Agent devices.

Cloud Entities

The following entities reside in the Cloud and handle device data and requests behind the scenes:

HTTP Router

The HTTP router routes HTTP requests to the relayr API to the proper endpoints and/or services. For example, if a user sends a GET request to the /devices endpoint, then the router will route the request to the Devices service.

Note that all requests must be routed through the Auth Service in order to verify that the requester is authorized to use the API.

Auth Service

The Auth Service provides authentication for all clients that send requests to the API. Before an API can execute a command or return a resource, it must go through the Auth Service and successfully authenticate the user’s account credentials.

Click here to learn more about authorization in the relayr Cloud.

Main API

The main API consists of all API endpoints except for the services endpoints. These include:

Aggregated Data Service

The Aggregated Data Service is the API endpoint that queries historical device data. It does so by accessing the Cloud Data Store directly.

Click here to learn more about how to use the Aggregated Data Service.

Click here for the full Aggregated Data Service API reference.


Services are the advanced features of the relayr platform that extend beyond merely sending and receiving data from connected devices. They perform more advanced functions with devices and other entities in the Cloud based on requests from users as well as data from devices.

The Services API endpoints include:

MQTT Broker

The MQTT Broker is a program that handles all MQTT data that passes through the Cloud. It passes MQTT data from devices along to the Data Router for delivery to the data store and the services. The Broker also receives data from the Router to be transmitted back to the devices.

Data Routing

relayr’s Data Router server handles the delivery of data to the proper recipients. It contains the logic necessary to route specific types of data to the right services that need to use them (e.g., sending device events to the Notification Service so that the subscribers are notified of the event).

Data Store

All device data that passes through the Cloud is sent to the Cloud Data Store. The data is stored in a variety of Cloud-distributed database clusters and made available for the Aggregated Data Service.

© 2017 relayr · Imprint