Tangle Domain Terminology

This application is called Tangle (or Tangle-UI for the frontend). Never refer to it as "Pipeline Studio" — that is a legacy name.

• tangle-ui: This frontend repo (React + TypeScript)
• tangle: The backend orchestration system
• Together they form the Tangle platform for building and running ML pipelines

Core Concepts

Pipeline

A pipeline is a directed acyclic graph (DAG) of components connected to produce a workflow. Represented as a ComponentSpec with a GraphImplementation. A pipeline defines:

• Inputs: Data entry points (graph-level inputs)
• Outputs: Data exit points (graph-level outputs)
• Tasks: Configured component instances
• Connections: Edges linking outputs to inputs

Component

A component is a reusable unit of computation defined by a ComponentSpec. Every component has:

• name, description
• inputs: Array of InputSpec
• outputs: Array of OutputSpec
• implementation: Either container (Docker) or graph (subgraph)
• metadata: Annotations, author, etc.

Component Spec (ComponentSpec)

The canonical data structure that fully describes a component's interface, implementation, and metadata. Compatible with Google Cloud Vertex AI Pipelines and Kubeflow v1 formats. Stored/shared as YAML (component.yaml). The TypeScript type definitions live in componentSpec.ts. Do not modify the ComponentSpec structure without express permission.

Task

A task is a configured instance of a component within a pipeline. A TaskSpec includes:

• componentRef: Reference to the component definition
• arguments: Configured input values (literals, graph input references, upstream task output references, or secrets)
• isEnabled: Optional conditional execution predicate
• executionOptions: Retry and caching strategies
• annotations: Metadata

Task Node

The visual representation of a task on the canvas. Has position, handles, and interaction callbacks. Node ID format: task_{taskId}.

Flex Node

A flex node is a freeform annotation element on the canvas (like a sticky note). It has a title, content, customizable colors, and font sizes. Flex nodes are purely decorative — they do not participate in task execution or data flow. Stored in ComponentSpec metadata annotations under the "flex-nodes" key. They can be locked to prevent accidental edits.

Ghost Node

A ghost node is a temporary, semi-transparent preview node that appears while the user is dragging to create a connection (with Meta key held). It shows what Input/Output node would be created if the user drops at that position. Ghost nodes are never persisted — they exist only during the drag interaction.

Input vs Input Component

These are different things:

• Input (InputSpec): A parameter definition on a component — has name, type, description, default value, optional flag
• Input Component (Input Node): A visual node on the canvas representing a graph-level input. It serves as a data source that feeds into task inputs. Node ID format: input_{inputName}

Output vs Output Component

Same distinction:

• Output (OutputSpec): A parameter definition on a component — has name, type, description
• Output Component (Output Node): A visual node on the canvas representing a graph-level output. It collects data from upstream task outputs. Node ID format: output_{outputName}

Task Type

The TaskType union: "task" | "input" | "output" — used to distinguish node types on the canvas.

Subgraph

A task whose component has a GraphImplementation instead of a ContainerImplementation. This enables nested pipelines. When viewing a subgraph, you navigate into its internal graph structure. Check with isSubgraph() from src/utils/subgraphUtils.ts.

Run / Pipeline Run

A run is a submitted instance of a pipeline for execution. Each run has:

• id: Unique identifier
• root_execution_id: The root execution
• pipeline_name, pipeline_digest
• status, statusCounts
• created_at, created_by

Execution

An execution is a lower-level entity — the execution of a single task within a run. Executions form a tree:

• A run has one root execution
• The root execution branches into child executions for each task
• Subgraph tasks have their own child execution trees

Run vs Execution: A run is the top-level container users interact with. Executions are the internal task-level tracking.

run_id vs execution_id: Use run_id (the id field on PipelineRunResponse) for run-level operations — listing, canceling, fetching metadata, and URL routes (/runs/$id). Use execution_id for task-level operations — fetching execution details, artifacts, logs, and container state (/api/executions/{id}/...). A run's root_execution_id bridges the two: it points to the root of the execution tree. Child execution IDs are found via details.child_task_execution_ids[taskId].

Execution Status

ContainerExecutionStatus: PENDING, RUNNING, SUCCEEDED, FAILED, etc. Runs aggregate these via TaskStatusCounts.

Edge / Connection

A directed connection in the graph. Three types:

• Task Output → Task Input: Data flows between tasks (TaskOutputArgument)
• Graph Input → Task Input: Pipeline inputs feed into tasks (GraphInputArgument)
• Task Output → Graph Output: Task outputs become pipeline outputs

Edge IDs are generated from source/target handle and input/output names.

Handle

A connection point on a node where edges attach:

• Input handles (target): Left side of task nodes, one per task input. ID: input_{inputName}
• Output handles (source): Right side of task nodes, one per task output. ID: output_{outputName}
• IO node handles: Input nodes have a source handle; output nodes have a target handle

Component Library

A hierarchical collection of components organized in folders. Types:

• Preloaded: Built-in components
• User Libraries: Custom user components
• Remote Libraries: Fetched from external sources
• GitHub Libraries: Components from GitHub repos

Annotations

Arbitrary key-value metadata (Record<string, unknown>) on components, tasks, inputs, outputs, and graph nodes. Used for canvas position/layout, z-index, visual styling, and custom metadata.

Secrets

Sensitive values (API keys, credentials) stored securely in the backend and referenced by name in task arguments via SecretArgument. Resolved at runtime — never embedded in pipeline definitions or exports.

{
  secret: {
    name: "my-api-key";
  }
}