Add Platform Data Flow explanation page

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
+<Guide>node-setup/configure-tls</Guide> 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 <Explanation>secrets</Explanation>.
+
+## 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
+<Guide>platform-setup</Guide>.
+
+## See Also
+
+- <Guide>node-setup/configure-tls</Guide>
+- <Explanation>platform</Explanation>
+- <Explanation>node</Explanation>
+- <Explanation>secrets</Explanation>
+- <Explanation>faqs</Explanation>

src/sidebar.ts

@@ -260,6 +260,7 @@ export const explanations = [
       "explanations/pipeline",
       "explanations/node",
       "explanations/platform",
+      "explanations/platform/data-flow",
       "explanations/language",
     ],
     "architecture",