From 298d07e0f6c867b40e48b6b7e11abc71429b65a1 Mon Sep 17 00:00:00 2001 From: Benno Evers Date: Wed, 13 May 2026 18:44:29 +0000 Subject: [PATCH 1/4] Document what data flows between nodes and the platform MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds an explanation page describing the node→platform WebSocket as a reverse tunnel used by the app for on-demand API calls, clarifying that pipeline data does not transit the platform except for live results streamed from app-initiated pipelines. --- .../docs/explanations/platform/data-flow.mdx | 93 +++++++++++++++++++ src/sidebar.ts | 1 + 2 files changed, 94 insertions(+) create mode 100644 src/content/docs/explanations/platform/data-flow.mdx diff --git a/src/content/docs/explanations/platform/data-flow.mdx b/src/content/docs/explanations/platform/data-flow.mdx new file mode 100644 index 000000000..4a7a484f4 --- /dev/null +++ b/src/content/docs/explanations/platform/data-flow.mdx @@ -0,0 +1,93 @@ +--- +title: Platform Data Flow +--- + +When a [node](/explanations/node) starts, it opens a single outbound, +TLS-encrypted WebSocket connection to the [platform](/explanations/platform). +This page describes what flows over that connection so you can reason about +privacy, compliance, and what an operator of the platform can see. + +For the bigger picture on TLS termination and trust boundaries, see the +[FAQ entry on data privacy](/explanations/faqs#can-tenzir-see-my-data). + +## The connection is a tunnel, not a feed + +The node does not push state to the platform. It opens the WebSocket, +authenticates, and then waits. The platform — and through it, the app — +uses this connection as a reverse tunnel to call the +[node API](/reference/node/api) on demand. + +In other words: whatever the app shows you about a node was pulled from +that node at the moment you asked for it. The platform does not maintain +a continuously updated mirror of the node's state. + +The node initiates the connection — the platform never connects to the +node. For nodes registered with the Tenzir-hosted platform, the endpoint +defaults to `wss://ws.tenzir.app:443/production`. See +node-setup/configure-tls for the TLS options. + +## What the app pulls on demand + +Anything you can retrieve via the [node API](/reference/node/api), the +platform can retrieve on behalf of an authenticated user in your +workspace. In practice this means: + +- The list of **pipelines** on the node, their TQL source, labels, and + lifecycle state. +- **Pipeline metrics** such as ingress/egress event and byte counters. +- **Diagnostics** (warnings and errors) emitted by pipelines. +- **Contexts** — their names, types, and, if you open them in the app, + their contents. +- **Packages** installed on the node and their configuration. +- **Schemas** the node has seen. + +These are fetched when a page or component in the app needs them. Close +the page and the requests stop. + +## Pipeline data does not flow through the platform + +Pipelines run entirely on the node. The events flowing through a +pipeline's operators are **not** routed through the platform, regardless +of where the pipeline was created. + +The single exception is a pipeline you run interactively from the app +(for example, in the Explorer). In that case the results stream +node → platform → browser for as long as the view is open, so the app +can render them. They are not persisted on the platform. + +## Secrets + +When a pipeline accesses a secret, the node requests its value from the +platform over the same encrypted channel, and the platform replies with +the resolved value. See secrets. + +## What is *not* sent + +The platform does **not** receive: + +- The **events stored in the node** (Parquet partitions, the catalog, + or query results) — unless you explicitly query them from the app. +- The **raw bytes** ingested from your sources. +- **Pipeline payloads** for pipelines that aren't being viewed live in + the app. +- **Node configuration files**, environment variables, or secret values + defined locally on the node. +- **Operating system logs** or anything outside the `tenzir-node` + process. + +## Encryption and trust + +The WebSocket is TLS-encrypted and terminates at the platform. In the +Tenzir-hosted editions, the operator of the platform (Tenzir) is +therefore technically able to observe data that traverses it during +interactive use. If this is unacceptable, run the platform yourself +with the [Sovereign Edition](https://tenzir.com/pricing) — see +platform-setup. + +## See Also + +- node-setup/configure-tls +- platform +- node +- secrets +- faqs diff --git a/src/sidebar.ts b/src/sidebar.ts index b23babb63..b6f49e7d3 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -260,6 +260,7 @@ export const explanations = [ "explanations/pipeline", "explanations/node", "explanations/platform", + "explanations/platform/data-flow", "explanations/language", ], "architecture", From bb8db380d54a1c8b8fa762d4e9c0cb7d98daa615 Mon Sep 17 00:00:00 2001 From: Benno Evers Date: Wed, 13 May 2026 21:38:26 +0000 Subject: [PATCH 2/4] Lead with explanation intro pattern Per .agents/references/content.md, explanation pages must open with "This page explains...". Rewrite the lead paragraph accordingly. --- src/content/docs/explanations/platform/data-flow.mdx | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/src/content/docs/explanations/platform/data-flow.mdx b/src/content/docs/explanations/platform/data-flow.mdx index 4a7a484f4..4355755d4 100644 --- a/src/content/docs/explanations/platform/data-flow.mdx +++ b/src/content/docs/explanations/platform/data-flow.mdx @@ -2,11 +2,14 @@ title: Platform Data Flow --- -When a [node](/explanations/node) starts, it opens a single outbound, -TLS-encrypted WebSocket connection to the [platform](/explanations/platform). -This page describes what flows over that connection so you can reason about +This page explains what data flows between a [node](/explanations/node) +and the [platform](/explanations/platform), so you can reason about privacy, compliance, and what an operator of the platform can see. +When a node starts, it opens a single outbound, TLS-encrypted WebSocket +connection to the platform. All communication between the two travels +over that connection. + For the bigger picture on TLS termination and trust boundaries, see the [FAQ entry on data privacy](/explanations/faqs#can-tenzir-see-my-data). From f926310a0e6179c40f073ebd6b794089a9c97377 Mon Sep 17 00:00:00 2001 From: Benno Evers Date: Wed, 13 May 2026 21:47:39 +0000 Subject: [PATCH 3/4] Use semantic components for inline cross-references Per .agents/references/content.md, prefer over plain markdown links when the link text matches the target page title. --- src/content/docs/explanations/platform/data-flow.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/explanations/platform/data-flow.mdx b/src/content/docs/explanations/platform/data-flow.mdx index 4355755d4..27a652fdf 100644 --- a/src/content/docs/explanations/platform/data-flow.mdx +++ b/src/content/docs/explanations/platform/data-flow.mdx @@ -2,8 +2,8 @@ title: Platform Data Flow --- -This page explains what data flows between a [node](/explanations/node) -and the [platform](/explanations/platform), so you can reason about +This page explains what data flows between a node +and the platform, so you can reason about privacy, compliance, and what an operator of the platform can see. When a node starts, it opens a single outbound, TLS-encrypted WebSocket From c41ca7877401dd9e52bebab4293ff0311b0af94a Mon Sep 17 00:00:00 2001 From: Benno Evers Date: Wed, 13 May 2026 22:13:00 +0000 Subject: [PATCH 4/4] Use Tenzir Node and Tenzir Platform terminology Refer to the components by their full product names throughout the page for consistency with the rest of the docs. --- .../docs/explanations/platform/data-flow.mdx | 83 ++++++++++--------- 1 file changed, 44 insertions(+), 39 deletions(-) diff --git a/src/content/docs/explanations/platform/data-flow.mdx b/src/content/docs/explanations/platform/data-flow.mdx index 27a652fdf..851fd3c49 100644 --- a/src/content/docs/explanations/platform/data-flow.mdx +++ b/src/content/docs/explanations/platform/data-flow.mdx @@ -2,89 +2,94 @@ title: Platform Data Flow --- -This page explains what data flows between a node -and the platform, so you can reason about -privacy, compliance, and what an operator of the platform can see. +This page explains what data flows between a +[Tenzir Node](/explanations/node) and the +[Tenzir Platform](/explanations/platform), so you can reason about +privacy, compliance, and what an operator of the Tenzir Platform can see. -When a node starts, it opens a single outbound, TLS-encrypted WebSocket -connection to the platform. All communication between the two travels -over that connection. +When a Tenzir Node starts, it opens a single outbound, TLS-encrypted +WebSocket connection to the Tenzir Platform. All communication between +the two travels over that connection. For the bigger picture on TLS termination and trust boundaries, see the [FAQ entry on data privacy](/explanations/faqs#can-tenzir-see-my-data). ## The connection is a tunnel, not a feed -The node does not push state to the platform. It opens the WebSocket, -authenticates, and then waits. The platform — and through it, the app — -uses this connection as a reverse tunnel to call the -[node API](/reference/node/api) on demand. +The Tenzir Node does not push state to the Tenzir Platform. It opens the +WebSocket, authenticates, and then waits. The Tenzir Platform — and +through it, the app — uses this connection as a reverse tunnel to call +the [node API](/reference/node/api) on demand. -In other words: whatever the app shows you about a node was pulled from -that node at the moment you asked for it. The platform does not maintain -a continuously updated mirror of the node's state. +In other words: whatever the app shows you about a Tenzir Node was +pulled from that node at the moment you asked for it. The Tenzir +Platform does not maintain a continuously updated mirror of the +Tenzir Node's state. -The node initiates the connection — the platform never connects to the -node. For nodes registered with the Tenzir-hosted platform, the endpoint -defaults to `wss://ws.tenzir.app:443/production`. See +The Tenzir Node initiates the connection — the Tenzir Platform never +connects to it. For nodes registered with the hosted Tenzir Platform, +the endpoint defaults to `wss://ws.tenzir.app:443/production`. See node-setup/configure-tls for the TLS options. ## What the app pulls on demand Anything you can retrieve via the [node API](/reference/node/api), the -platform can retrieve on behalf of an authenticated user in your +Tenzir Platform can retrieve on behalf of an authenticated user in your workspace. In practice this means: -- The list of **pipelines** on the node, their TQL source, labels, and - lifecycle state. +- The list of **pipelines** on the Tenzir Node, their TQL source, + labels, and lifecycle state. - **Pipeline metrics** such as ingress/egress event and byte counters. - **Diagnostics** (warnings and errors) emitted by pipelines. - **Contexts** — their names, types, and, if you open them in the app, their contents. -- **Packages** installed on the node and their configuration. -- **Schemas** the node has seen. +- **Packages** installed on the Tenzir Node and their configuration. +- **Schemas** the Tenzir Node has seen. These are fetched when a page or component in the app needs them. Close the page and the requests stop. -## Pipeline data does not flow through the platform +## Pipeline data does not flow through the Tenzir Platform -Pipelines run entirely on the node. The events flowing through a -pipeline's operators are **not** routed through the platform, regardless -of where the pipeline was created. +Pipelines run entirely on the Tenzir Node. The events flowing through a +pipeline's operators are **not** routed through the Tenzir Platform, +regardless of where the pipeline was created. The single exception is a pipeline you run interactively from the app (for example, in the Explorer). In that case the results stream -node → platform → browser for as long as the view is open, so the app -can render them. They are not persisted on the platform. +Tenzir Node → Tenzir Platform → browser for as long as the view is +open, so the app can render them. They are not persisted on the +Tenzir Platform. ## Secrets -When a pipeline accesses a secret, the node requests its value from the -platform over the same encrypted channel, and the platform replies with -the resolved value. See secrets. +When a pipeline accesses a secret, the Tenzir Node requests its value +from the Tenzir Platform over the same encrypted channel, and the +Tenzir Platform replies with the resolved value. See +secrets. ## What is *not* sent -The platform does **not** receive: +The Tenzir Platform does **not** receive: -- The **events stored in the node** (Parquet partitions, the catalog, - or query results) — unless you explicitly query them from the app. +- The **events stored in the Tenzir Node** (Parquet partitions, the + catalog, or query results) — unless you explicitly query them from + the app. - The **raw bytes** ingested from your sources. - **Pipeline payloads** for pipelines that aren't being viewed live in the app. -- **Node configuration files**, environment variables, or secret values - defined locally on the node. +- **Configuration files**, environment variables, or secret values + defined locally on the Tenzir Node. - **Operating system logs** or anything outside the `tenzir-node` process. ## Encryption and trust -The WebSocket is TLS-encrypted and terminates at the platform. In the -Tenzir-hosted editions, the operator of the platform (Tenzir) is +The WebSocket is TLS-encrypted and terminates at the Tenzir Platform. +In the editions where Tenzir hosts the Tenzir Platform, Tenzir is therefore technically able to observe data that traverses it during -interactive use. If this is unacceptable, run the platform yourself -with the [Sovereign Edition](https://tenzir.com/pricing) — see +interactive use. If this is unacceptable, host the Tenzir Platform +yourself with the [Sovereign Edition](https://tenzir.com/pricing) — see platform-setup. ## See Also