Core ChainGraph domain concepts - flows, nodes, ports, edges, and execution. Use for ANY ChainGraph development to understand the fundamental abstractions. Explains what flows are, how nodes process data, port types (9 types), edge data transfer, and execution lifecycle. 19 FlowEventTypes, 21 ExecutionEventEnums. Triggers: chaingraph, flow, node, port, edge, execution, what is, how does, concept, architecture, event types.
⭐10stars🔀2forks📁View on GitHub🕐Updated Dec 30, 2025⬇️2downloads
This Claude skill provides a comprehensive guide to the core abstractions of ChainGraph, a flow-based programming framework for building visual computational graphs. It covers essential domain concepts including Flows (DAGs), Nodes (computational units), Ports (typed data connectors), Edges (connections), and the Execution Engine. Ideal for developers building complex agentic workflows, it explains the lifecycle, event types, and data transfer mechanisms required to design and implement robust, scalable, and type-safe computational architectures.
Use Cases
Designing complex agentic workflows: Understanding how to structure nodes and edges to create a Directed Acyclic Graph (DAG) for multi-step AI tasks and automated processes.
Implementing custom computational nodes: Utilizing the node lifecycle (Idle to Completed) and metadata definitions to build reusable, discrete logic units within the ChainGraph framework.
Managing data flow and type safety: Leveraging the nine specialized port types (such as stream, secret, and object) to ensure reliable and secure data transfer between interconnected nodes.
Debugging and monitoring execution: Utilizing the 21 ExecutionEventEnums and 19 FlowEventTypes to track real-time status, handle errors, and implement observability in production workflows.
Orchestrating parallel execution: Configuring the ExecutionEngine with specific concurrency and timeout options to optimize the performance of large-scale computational graphs.
name
chaingraph-concepts
description
Core ChainGraph domain concepts - flows, nodes, ports, edges, and execution. Use for ANY ChainGraph development to understand the fundamental abstractions. Explains what flows are, how nodes process data, port types (9 types), edge data transfer, and execution lifecycle. 19 FlowEventTypes, 21 ExecutionEventEnums. Triggers: chaingraph, flow, node, port, edge, execution, what is, how does, concept, architecture, event types.
ChainGraph Core Concepts
ChainGraph is a flow-based programming framework for building visual computational graphs. This skill covers the fundamental domain concepts that ALL agents need to understand.
A Node is a discrete computational unit that performs a specific operation on input data and produces output. Nodes are the building blocks of flows.
Node Lifecycle
Idle → Ready → Executing → Completed
↓
Error
NodeStatus Enum
enum NodeStatus {
Idle = 'idle', // Initial state
Initialized = 'initialized',
Ready = 'ready', // Ready to execute
Pending = 'pending', // Waiting for dependencies
Executing = 'executing', // Currently running
Completed = 'completed', // Successfully finished
Skipped = 'skipped', // Skipped (condition not met)
Error = 'error', // Failed with error
Disposed = 'disposed', // Cleaned up
}
Key Properties
Property
Type
Description
id
string
Unique identifier
metadata
NodeMetadata
Type, title, category, description
status
NodeStatus
Current execution status
ports
Map<string, IPort>
Input and output ports
Key Methods
// Execute the node
node.execute(context: ExecutionContext): Promise<NodeExecutionResult>
// Get a port by ID
node.getPort(portId: string): IPort | undefined
// Validate configuration
node.validate(): Promise<NodeValidationResult>
// Reset to initial state
node.reset(): Promise<void>
NodeMetadata
interface NodeMetadata {
type: string // Node class name (required)
title?: string // Display name
category?: NodeCategory // e.g., 'math', 'flow-control', 'ai'
description?: string
version?: number
icon?: string
tags?: string[]
parentNodeId?: string // If nested in group
ui?: NodeUIMetadata // Position, dimensions, etc.
}
A Port is a typed input or output connector on a Node through which data flows. Ports are strongly typed and support primitives, arrays, objects, and streams.
Port Direction
type PortDirection = 'input' | 'output' | 'passthrough'
Input: Receives data from connected output ports
Output: Sends data to connected input ports
Passthrough: Both input and output
Port Types (9 Total)
Type
Description
Example Use
string
Text values
Names, prompts, API keys
number
Numeric values
Counts, scores, coordinates
boolean
True/false
Flags, conditions
array
List of typed items
Data batches, collections
object
Structured data with schema
Complex configs, records
stream
Async multi-channel data
Real-time data, LLM tokens
enum
Fixed set of options
Dropdown selections
secret
Encrypted sensitive data
API keys, passwords
any
Untyped (avoid if possible)
Dynamic data
Port Configuration
Each port type has a specific config interface:
interface StringPortConfig {
type: 'string'
defaultValue?: string
minLength?: number
maxLength?: number
pattern?: RegExp // Validation regex
}
interface NumberPortConfig {
type: 'number'
defaultValue?: number
min?: number
max?: number
step?: number
integer?: boolean
}
interface ArrayPortConfig<Item> {
type: 'array'
itemConfig: IPortConfig // Type of each item
minLength?: number
maxLength?: number
isMutable?: boolean // Can items be added/removed?
}
interface ObjectPortConfig<Schema> {
type: 'object'
schema: IObjectSchema // Properties definition
isSchemaMutable?: boolean
}
An Edge is a directed connection from an output port of one node to an input port of another node, enabling data flow.
Edge Status
enum EdgeStatus {
Active = 'active', // Connection working
Inactive = 'inactive', // Disabled
Error = 'error', // Transfer failed
}
Key Properties
Property
Type
Description
id
string
Unique identifier
sourceNode
INode
Node with output port
sourcePort
IPort
Output port
targetNode
INode
Node with input port
targetPort
IPort
Input port
metadata
EdgeMetadata
Label, anchors, version
EdgeMetadata
interface EdgeMetadata {
label?: string // Display label
anchors?: EdgeAnchor[] // Control points for custom paths
version?: number // For optimistic updates
}
interface EdgeAnchor {
id: string
x: number // Coordinate
y: number
index: number // Order in path
}
1. Flow loads nodes and edges
2. ExecutionEngine resolves dependencies (topological sort)
3. Nodes execute in parallel where possible
4. Output port values transfer to connected input ports
5. Events stream in real-time
6. Flow completes or fails
Related Skills
types-architecture - Deep dive into the types package