Data Flow & Automation Architecture Guide

This guide explains how data moves through Virtuino Cloud — from the moment a device sends a value, all the way to storage, real-time dashboards, automation rules, and scripts. Understanding this flow helps you design reliable automations, avoid common pitfalls, and get the most out of the platform's capabilities.

1. How Data Enters the Platform

Every value that reaches Virtuino Cloud arrives through one of the following entry points. Each one identifies itself with a source tag that travels with the data throughout its entire journey inside the platform.

2. The Central Hub: How Every Value is Processed

No matter where a value originates, it always passes through the platform's central processing function. This hub performs the same sequence of actions for every incoming value:

1. Forward via MQTT (only for MQTT-sourced values). If the value arrived via MQTT from a device, the platform immediately re-publishes it on the outbound topic (/out/) so that other MQTT subscribers (apps, displays, other devices) can receive it in real time.
2. Save to the database. The value is written to persistent storage. If the field is configured as historical, every value is appended. If it is configured as live-only, only the latest value is kept.
3. Publish outbound via MQTT (for rules, scripts, schedulers). If an automation component has the "MQTT Publish" option enabled, the value is sent out via MQTT so devices can receive it.
4. Push to real-time dashboards. The value is broadcast instantly to all open dashboards that are displaying that field.
5. Trigger Automation Rules (if applicable — see Section 9 for conditions).
6. Trigger Scripts (if applicable — see Section 9 for conditions).

3. MQTT Topics — Inbound vs. Outbound

MQTT is a publish/subscribe messaging protocol. Devices publish values to "topics" — think of these as named channels. The platform subscribes to topics to receive device data, and also publishes to topics to send data back to devices.

Virtuino Cloud uses a strict namespace separation between incoming and outgoing MQTT traffic. This is one of the most important architectural decisions in the platform, as it eliminates an entire class of potential infinite loops.

{shortId}/in/device/{deviceName}/{fieldName}
{shortId}/in/{fieldName}

abc123/in/device/greenhouse/temperature

{shortId}/out/device/{deviceName}/{fieldName}
{shortId}/out/{fieldName}

abc123/out/device/greenhouse/temperature

Topic Structure Reference

Publishing without a named device

If your device does not have a specific device name, you can publish directly to a field without the device/{name} part. The platform will assign the value to a generic device called unspecified:

// Simplified topic without a device name:
{shortId}/in/{fieldName}

// Example:
abc123/in/temperature

4. Real-Time Dashboards via WebSocket

Every time any value is processed by the platform hub — regardless of source — it is instantly broadcast to all open dashboards that are displaying that field. This happens through an internal real-time channel (WebSocket), so there is no need to refresh the page.

This means:

• A value sent by an MQTT device appears on the dashboard in under a second.
• A value written by a Rule or Script also appears on the dashboard immediately.
• Multiple users on different browsers all see the same live update simultaneously.

5. Automation Rules

Automation Rules are condition-based triggers. You define a condition (e.g., "when field temperature is greater than 80") and an action (e.g., "write value 1 to field alarm"). When the condition is met, the action fires automatically.

How a Rule Works

1. A new value arrives for a monitored field.
2. The platform evaluates all active rules that watch that field.
3. If a rule's condition is met, it performs its configured action: writing a value to a target field, sending an email, sending a push notification, or any combination.
4. The written value enters the hub with source AUTOMATION_RULE.

Rule Triggering Behaviour

Rules use an internal triggered flag. When a condition is first met, the rule fires and sets the flag to true. If the condition remains true on subsequent data arrivals, the action does not fire again (it already fired). The flag resets to false only when the condition is no longer met — this prevents the rule from repeatedly firing while the condition is continuously true.

6. Scripts

Scripts allow you to write JavaScript logic that runs automatically when data arrives or on a timer. They can read multiple input fields, perform calculations, and write results to output fields.

Two execution modes

IO Mapping

Scripts interact with platform data through a mapping table, not by directly naming database tables. Each row in the mapping table declares:

• Direction IN: A field whose latest value is available to the script as a read-only input.
• Direction OUT: A field that the script can write results to.
• Is Trigger: (for IN rows only) Whether a new value on this field should trigger the script to run immediately.
• MQTT Publish: (for OUT rows only) Whether the written value should also be sent out via MQTT.

Script safety limits

Each script runs in an isolated sandbox with a strict 50ms execution timeout. If the script takes longer than 50ms, it is terminated. This protects the platform from poorly written scripts consuming server resources. Additionally, script-to-script cascade chains are limited to a maximum depth of 5 levels.

7. Schedulers

Schedulers allow you to write a specific value to a specific field at a fixed time or on a repeating interval — without any condition or script logic. They are the simplest form of automation: "every day at 08:00, write value 1 to field morning_flag".

Values written by schedulers enter the hub with source SCHEDULE and are eligible to trigger both rules and scripts, exactly like values from external devices.

8. The Automation Execution Order

When any value arrives at the platform hub, the following sequence always takes place in this order:

9. Loop Prevention: How the Platform Protects Itself

The most dangerous scenario in any automation platform is an infinite loop: a value triggers a rule, which writes a new value, which triggers a script, which writes another value, which triggers the rule again — endlessly. This would fill the database, consume all server resources, and crash the platform.

Virtuino Cloud prevents loops at three levels:

Level 1 — Architectural: MQTT Namespace Isolation

The platform subscribes only to +/in/# topics. All values it publishes go to +/out/# topics. Since the platform never subscribes to +/out/#, its own outbound MQTT messages can never come back to it. This makes MQTT-based loops architecturally impossible — not just prevented by code logic, but structurally impossible by design.

Level 2 — Source-Based: Smart Trigger Filtering

The platform tracks the source of every value and applies strict rules about what can trigger what:

Level 3 — Script depth limit

Scripts that are triggered by other scripts (through a chain of field writes) are limited to a maximum cascade depth of 5 levels. If a script's output triggers another script, and that script's output triggers another, and so on, the chain is cut at level 5 regardless of conditions.

10. Common Problems & How to Avoid Them

11. Quick Reference: Source Tags

The source tag is attached to every value in the platform. It determines what that value is allowed to trigger and is visible in the Data Monitor and automation logs.

Virtuino Cloud Platform — Data Flow & Automation Architecture Guide