tangle-domain

name	tangle-domain
description	Domain terminology and concepts for Tangle. Use whenever discussing, naming, or working with pipelines, runs, components, tasks, inputs, outputs, executions, or any Tangle domain concepts.

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.

// SecretArgument structure
{
  secret: {
    name: "my-api-key";
  }
}