DEV Community: Nick

Part 15: Workflow Patterns and Recipes - Data Transformation

Nick — Fri, 26 Jun 2026 08:03:00 +0000

As we conclude this 15-part series on Vyshyvanka, we want to leave you with practical tools. One of the most common challenges in workflow automation is not moving data, but transforming it. Today, we look at the patterns we use to map, clean, and reshape data as it flows through your pipelines.

The Transformation Challenge

In a real-world workflow, you rarely get the data exactly in the format you need. Service A might return a deeply nested JSON object, while Service B expects a flat structure with different field names. Vyshyvanka handles this through its expression engine and Code Node — giving you both declarative and programmatic transformation options.

Pattern 1: Path Projection with Expressions

When you have a large JSON response and only need specific values, use expressions in your node configuration to extract exactly what you need:

{{ nodes.api.data.items[0].user.id }}

This plucks a deeply nested ID from an API response and passes it as a clean input to your next node. You can use this directly in any node's configuration field.

For more complex extraction, combine with built-in functions:

{{ toUpper(nodes.api.data.items[0].user.name) }}
{{ concat(nodes.user.data.firstName, " ", nodes.user.data.lastName) }}
{{ coalesce(nodes.api.data.nickname, nodes.api.data.name, "Anonymous") }}

Pattern 2: Structural Remapping with Code Nodes

When you need to transform the entire shape of the data, the Code Node is your best tool. It supports two runtimes:

JavaScript (via Jint engine):

General-purpose JavaScript for complex transformations. You have access to:

input — the full input data from upstream nodes
executionId — current execution ID
workflowId — current workflow ID
log(message) — logging that appears in execution output
getItems() — returns input as an array (wraps single values)
toJson(value) — serializes a value to a JSON string

// Remap an API response to a different structure
log("Transforming user data: " + input.email);
return {
    email: input.email.toLowerCase(),
    fullName: input.firstName + " " + input.lastName,
    isVerified: input.status === "active",
    createdYear: new Date(input.createdAt).getFullYear()
};

JSONata:

A declarative query and transformation language, ideal for complex path selection and restructuring:

{
    "users": items.{
        "id": userId,
        "name": firstName & " " & lastName,
        "active": status = "active"
    },
    "total": $count(items)
}

JSONata shines when you need to reshape deeply nested structures without imperative loop code.

Pattern 3: Batch Processing with runForEachItem

Both JavaScript and JSONata support two execution modes:

runOnce: Executes your code against the full input object. Use this for single-item transformations or when you need access to the entire dataset.
runForEachItem: If your input is an array, the engine executes your logic for every item, collecting the results into a new array.

// Mode: runForEachItem
// 'input' here is a single item from the array
return {
    id: input.id,
    label: input.name.toUpperCase(),
    processed: true
};

This is the equivalent of a .map() operation, but managed by the engine with proper error handling and logging for each item.

Pattern 4: Conditional Routing with Logic Nodes

Not all transformation is about reshaping data — sometimes you need to route data differently based on its content. The Switch node evaluates a value and routes to different output ports:

Configure the switch value: {{ nodes.api.data.status }}
Define cases: "active" → port A, "suspended" → port B, default → port C

Each downstream branch can then apply its own transformation logic appropriate to that case.

The If node handles binary decisions:

Condition: {{ nodes.check.data.amount }} > threshold
True branch: process normally
False branch: send alert

Pattern 5: Aggregation with Loop + Merge

For workflows that need to process a collection and then aggregate the results:

Loop Node: Iterates over an array, executing a subgraph for each item.
Subgraph nodes: Transform/enrich each item (API calls, lookups, etc.).
Loop completion: The loop node collects all outputs from its "done" port.
Merge Node: Combines data from multiple branches into a single object.

The loop node exposes per-iteration context:

{{ nodes.loop.data.index }}        // Current iteration index
{{ nodes.loop.data.item }}         // Current item
{{ nodes.loop.data.isFirst }}      // Boolean
{{ nodes.loop.data.isLast }}       // Boolean
{{ nodes.loop.data.totalCount }}   // Total items

Pattern 6: Data Enrichment Pipeline

A common pattern is fetching additional data for each item in a collection:

HttpRequest → Get list of orders from API
Loop → For each order:
- HttpRequest → Fetch customer details by {{ nodes.loop.data.item.customerId }}
- Code Node → Merge order + customer into enriched object
DatabaseQuery → Store enriched results

Each step references the previous step's output through expressions, creating a data pipeline that transforms raw API responses into enriched, business-ready objects.

Best Practices

Keep transformations close to their consumer: Transform data in the node configuration or a Code Node immediately before the node that needs it.
Use expressions for simple extractions: {{ nodes.api.data.user.name }} is clearer than a Code Node for simple path access.
Use Code Nodes for complex logic: Multi-field remapping, conditional logic, and calculations belong in Code Nodes where they are testable and readable.
Prefer JSONata for pure data reshaping: When you are only restructuring JSON without side effects, JSONata expressions are more concise than JavaScript.
Use runForEachItem for array transformations: It handles iteration, error collection, and result aggregation automatically.

Wrapping Up the Series

We hope this series has shown you that Vyshyvanka is built for the real world — secure, extensible, and performant. We started with basic triggers and ended with complex data transformation patterns. The platform gives you the building blocks; how you combine them is up to your creativity.

The community is the final piece of the puzzle. Now it is your turn. Go build something, share your custom nodes, and let us know what you think.

Check out the project source code here: https://github.com/homolibere/Vyshyvanka

Part 14: Community and Ecosystem - Contributing to Vyshyvanka

Nick — Thu, 25 Jun 2026 09:02:00 +0000

It is clear that Vyshyvanka is more than just code — it is an ecosystem. The true power of an open-source workflow engine lies in its community. Today, we want to talk about how you can get involved, whether you are interested in pushing the boundaries of the core engine or building specialized solutions with custom plugins.

The Core Engine vs. The Plugin Ecosystem

A common question we get is: 'Should I contribute a PR to the core engine, or should I build a separate plugin?' The answer depends entirely on the scope of your contribution.

When to Contribute to Core

The core engine (Vyshyvanka.Core, Vyshyvanka.Engine, Vyshyvanka.Api, Vyshyvanka.Designer) should be reserved for changes that benefit every user of the platform. Good candidates for core contributions:

Performance improvements to the execution pipeline
New fundamental port types or expression functions
Bug fixes in the engine, validation, or persistence layers
Enhancements to the Designer UI (canvas, node editor, property editors)
Improvements to the API surface (new endpoints, better error responses)
Documentation improvements

These changes require careful review and testing because they impact every installation. We encourage PRs here, but we also ask that you open an issue first so we can discuss the architectural impact.

When to Build a Plugin

Plugins (./plugins/) are the best way to extend functionality without increasing the maintenance burden of the core. Good candidates for plugins:

Integration with a specific third-party SaaS tool (CRM, CI/CD, monitoring)
Custom nodes specific to your industry or use case
Experimental node behaviors that are not yet ready for core
Proprietary integrations you want to keep separate from the open source project

Plugins are independent, versionable, and can be maintained outside the core release cycle. They empower you to solve your specific problems immediately without waiting for a core release.

Project Structure at a Glance

Understanding where things live is key to contributing effectively:

Vyshyvanka/
├── src/
│   ├── Vyshyvanka.Core/        # Domain layer (zero dependencies)
│   ├── Vyshyvanka.Engine/      # Execution engine, persistence, plugins
│   ├── Vyshyvanka.Api/         # REST API
│   ├── Vyshyvanka.Designer/    # Blazor WASM UI
│   ├── Vyshyvanka.AppHost/     # .NET Aspire orchestration
│   └── Vyshyvanka.ServiceDefaults/
├── plugins/
│   ├── Vyshyvanka.Plugin.AdvancedHttp/
│   ├── Vyshyvanka.Plugin.GitLab/
│   ├── Vyshyvanka.Plugin.Jira/
│   └── Vyshyvanka.Plugin.Tmplt/  # Starter template!
├── tests/
│   └── Vyshyvanka.Tests/
└── docs/

Dependencies flow strictly downward. Core has zero dependencies. Engine depends on Core. Api depends on Core and Engine. Plugins depend only on Core.

Getting Started with Plugin Development

The fastest way to start is with the template plugin:

Copy the template: Duplicate plugins/Vyshyvanka.Plugin.Tmplt/ and rename it.
Update PluginInfo.cs: Set your plugin ID, name, version, and author.
Create your nodes: Inherit from BasePluginNode, add [NodeDefinition] and [ConfigurationProperty] attributes.
Build and test: The test project can reference your plugin directly.
Package: Publish as a NuGet package for easy distribution.

Here is the minimal structure:

// PluginInfo.cs
[assembly: Plugin(
    "com.yourorg.myplugin",
    Name = "My Plugin",
    Version = "1.0.0",
    Description = "Does something useful",
    Author = "Your Name")]

// Nodes/MyCustomNode.cs
[NodeDefinition(
    Name = "My Custom Action",
    Description = "Does the thing",
    Icon = "fa-solid fa-star")]
[ConfigurationProperty("apiUrl", "string", Description = "API endpoint", IsRequired = true)]
public class MyCustomNode : BasePluginNode
{
    public override string Type => "my-custom-action";
    public override NodeCategory Category => NodeCategory.Action;

    public override async Task<NodeOutput> ExecuteAsync(NodeInput input, IExecutionContext context)
    {
        var apiUrl = GetRequiredConfigValue<string>(input, "apiUrl");
        // Your logic here...
        return SuccessOutput(JsonSerializer.SerializeToElement(new { result = "done" }));
    }
}

Contributing to Core: Guidelines

If you want to contribute to the core:

Open an issue first: Describe the problem and your proposed solution. This helps us maintain consistency and prevents wasted effort.
Follow conventions: File-scoped namespaces, primary constructors for DI, CancellationToken in every async method, AwesomeAssertions in tests.
Write tests: Every change needs appropriate test coverage — unit tests for logic, integration tests for API changes.
Respect the dependency rules: Never introduce an upward or circular reference between projects.
Check the ripple effect: If you change an interface in Core, update all implementations in Engine.

Running the Full Stack

# Build everything
dotnet build

# Run all tests
dotnet test

# Start the full application (API + Designer)
dotnet run --project src/Vyshyvanka.AppHost

# Start just the API
dotnet run --project src/Vyshyvanka.Api

A Growing Ecosystem

Every plugin you build and every bug you fix makes Vyshyvanka more valuable for everyone else. Whether you are an enterprise developer building mission-critical workflows or a hobbyist automating your home server, your contribution helps shape the future of open-source workflow automation.

We are excited to see what you build.

In the final part of this series, we will discuss Part 15: Workflow Patterns and Recipes - Data Transformation. Stay tuned!

Check out the project source code here: https://github.com/homolibere/Vyshyvanka

Part 13: Deployment Strategies - Orchestrating Vyshyvanka with .NET Aspire

Nick — Wed, 24 Jun 2026 08:02:00 +0000

As we move from development to production, deployment complexity often becomes the biggest bottleneck. For Vyshyvanka, we chose .NET Aspire as our development orchestration framework and as the foundation for production-ready deployments. Today, we look at how Aspire simplifies running a multi-service workflow engine.

Why Aspire?

Traditional development setup means manually configuring your API, your Blazor frontend, your database, and ensuring they can discover each other. If one service's port changes, everything breaks. Aspire solves this by treating the entire application as a single, orchestrated 'app model'. This app model describes how your services relate to each other — what resources they need, what ports they share, and how they discover each other via service discovery.

Our AppHost

The Vyshyvanka.AppHost project defines our application topology in C#:

var builder = DistributedApplication.CreateBuilder(args);

// Check if PostgreSQL mode is enabled
var usePostgres = builder.Configuration["UsePostgres"]?
    .Equals("true", StringComparison.OrdinalIgnoreCase) == true;

IResourceBuilder<ProjectResource> api;

if (usePostgres)
{
    // Production: PostgreSQL with persistent volume
    var postgres = builder.AddPostgres("postgres")
        .WithDataVolume("vyshyvanka-postgres-data");
    var database = postgres.AddDatabase("vyshyvankadb");

    api = builder.AddProject<Projects.Vyshyvanka_Api>("api")
        .WithReference(database)
        .WaitFor(database);
}
else
{
    // Development: SQLite (no external dependencies)
    api = builder.AddProject<Projects.Vyshyvanka_Api>("api");
}

// Designer discovers API via service discovery
builder.AddProject<Projects.Vyshyvanka_Designer>("designer")
    .WithReference(api)
    .WaitFor(api);

builder.Build().Run();

This is actual production code from our repository. A few things to note:

Conditional infrastructure: The same AppHost supports both SQLite (for quick local dev) and PostgreSQL (for production-like environments). A single environment variable flips the switch.
Service discovery: The Designer automatically discovers the API endpoint — no hard-coded URLs in configuration files.
Dependency ordering: WaitFor ensures the API doesn't start until the database is ready, and the Designer doesn't start until the API is accepting requests.

Development Experience

Running the full stack locally is a single command:

dotnet run --project src/Vyshyvanka.AppHost

This starts:

The PostgreSQL container (if configured) with a persistent data volume
The API service with proper connection strings injected
The Blazor WebAssembly Designer with API endpoint configured

The Aspire dashboard gives you a unified view of all services, their logs, and distributed traces — all without any additional configuration.

Service Defaults

The Vyshyvanka.ServiceDefaults project provides shared configuration that every service gets automatically:

Health checks — standardized readiness and liveness probes
OpenTelemetry — distributed tracing and metrics collection
Resilience — default HTTP client resilience policies
Service discovery — automatic endpoint resolution

Each service opts in with a single line: builder.AddServiceDefaults().

Containerization

Aspire is built on a container-first mindset. In development, it manages Docker containers for infrastructure (PostgreSQL). For production deployment, the same application model can generate deployment manifests for container orchestrators.

Because our application is already decomposed into well-defined services with explicit dependencies, the transition from local development to containerized production is straightforward:

The API and Designer are standard .NET web applications — they containerize with the default .NET SDK container support.
Database connection strings are injected via environment variables, whether running locally or in a container.
Service discovery works the same way in both environments.

Environment-Specific Configuration

We handle the dev/prod split cleanly through the AppHost configuration:

Environment	Database	Auth Provider	Credential Storage
Development	SQLite (file)	Built-in (seeded users)	Built-in (AES-256)
Staging	PostgreSQL (container)	Keycloak/Authentik	Built-in (AES-256)
Production	PostgreSQL (managed)	OIDC provider	Vault/OpenBao

The application code is identical across all environments. Only the infrastructure wiring changes.

Observability Built In

One of the biggest wins with Aspire is built-in observability. Through ServiceDefaults, every HTTP request, database query, and cross-service call is automatically traced with OpenTelemetry. When a workflow fails in production, you can trace the entire request path through the system using standard observability tools (Jaeger, Zipkin, Application Insights, etc.).

Deployment Consistency

The 'it works on my machine' problem is eliminated. With Aspire, your infrastructure is defined as code alongside your logic. The topology you test locally is the same topology that runs in production. You don't manage shell scripts to wire up services — you manage the C# model that defines your application architecture.

By using Aspire as our orchestration layer, we have drastically reduced the time it takes to go from a local feature to a testable deployment.

In the next part, we will discuss Part 14: Community and Ecosystem - Contributing to Vyshyvanka. Stay tuned!

Check out the project source code here: https://github.com/homolibere/Vyshyvanka

Part 12: Performance Optimization - High-Throughput Concurrency

Nick — Tue, 23 Jun 2026 07:01:00 +0000

In the world of workflow automation, efficiency is not just a nice-to-have; it is a fundamental requirement. A single workflow engine instance might need to manage hundreds of concurrent executions, each waiting on I/O, external APIs, or database operations. Today, we explore how Vyshyvanka achieves high-throughput performance using .NET's powerful concurrency model.

The Async-First Architecture

Vyshyvanka was built with an async-first philosophy. We recognized early on that workflow engines are inherently I/O-bound. You are constantly waiting: waiting for a database row to lock, waiting for an API to respond, or waiting for a disk write to confirm.

If we were to use traditional synchronous threads, we would quickly exhaust the thread pool and bring the system to a halt. By using async/await everywhere, we ensure that while a workflow waits for I/O, the underlying thread is returned to the .NET thread pool to handle other work. This allows a relatively small number of threads to manage hundreds of concurrent workflow executions.

Concurrency Control with SemaphoreSlim

The engine uses SemaphoreSlim to limit the degree of parallelism at each execution level. This prevents a single large workflow from saturating all available resources:

private async Task<NodeExecutionResult[]> ExecuteLevelWithThrottlingAsync(
    Workflow workflow, List<string> level, IExecutionContext context,
    ConcurrentBag<NodeExecutionResult> nodeResults, int maxParallelism,
    CancellationToken cancellationToken)
{
    using var semaphore = new SemaphoreSlim(maxParallelism, maxParallelism);

    var tasks = level.Select(async nodeId =>
    {
        await semaphore.WaitAsync(cancellationToken);
        try
        {
            return await ExecuteNodeInWorkflowAsync(
                workflow, nodeId, context, nodeResults, cancellationToken);
        }
        finally
        {
            semaphore.Release();
        }
    }).ToList();

    return await Task.WhenAll(tasks);
}

The default parallelism is Environment.ProcessorCount * 2, configurable per workflow via workflow.Settings.MaxDegreeOfParallelism. This gives you fine-grained control — a lightweight data-sync workflow might run with parallelism of 1, while a fan-out notification workflow might use 20.

Thread Safety Through Design

Managing concurrency requires careful handling of shared state. Here is our approach:

Thread-Safe Collections: The engine tracks active executions and node results using ConcurrentDictionary and ConcurrentBag:

private readonly ConcurrentDictionary<Guid, CancellationTokenSource> _activeExecutions = new();

// Node results are collected concurrently from parallel branches
var nodeResults = new ConcurrentBag<NodeExecutionResult>();

Scoped Execution Context: Each execution gets its own IExecutionContext instance. The context stores node outputs and execution variables. While the context is mutated during execution (nodes write their outputs into it), each execution is isolated — one workflow's context never touches another's.
Linked Cancellation: Each execution creates a linked CancellationTokenSource so that cancellation can come from either the caller or the engine's CancelExecutionAsync method:

using var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
_activeExecutions[context.ExecutionId] = cts;

Minimizing Thread Pool Starvation

A common trap in .NET is 'sync-over-async' — calling .Result or .Wait() on an asynchronous method. This blocks a thread, preventing it from doing other work, and is the primary cause of thread pool starvation. We enforce a strict rule in our codebase: No blocking calls. Every call from the engine core through the plugin layer must be properly awaited.

This rule extends to plugin nodes. Plugin execution goes through IPluginHost.ExecuteNodeInIsolationAsync with a configurable timeout. If a plugin blocks or hangs, the timeout fires and the node is marked as failed without affecting other executions.

Memory Efficiency

We apply several techniques to reduce allocations in the hot path:

Cached empty objects: A single JsonDocument.Parse("{}").RootElement.Clone() is reused across all nodes that need an empty input, avoiding repeated allocations.
StringBuilder reuse: Expression evaluation uses StringBuilder with pre-estimated capacity for string interpolation.
Compiled regex: The expression pattern matching uses source-generated [GeneratedRegex] for zero-allocation matching.

// Cached once, shared across all executions
private static readonly JsonElement EmptyObjectElement =
    JsonDocument.Parse("{}").RootElement.Clone();

Plugin Timeout Protection

External plugin nodes get an additional layer of protection. The engine wraps plugin execution with a timeout to prevent runaway code from blocking the pipeline:

private static readonly TimeSpan DefaultPluginTimeout = TimeSpan.FromSeconds(30);

private async Task<NodeOutput> ExecuteNodeInstanceAsync(
    INode nodeInstance, NodeInput input, IExecutionContext context, TimeSpan timeout)
{
    if (_pluginHost is not null && _pluginHost.IsPluginNode(nodeInstance.Type))
        return await _pluginHost.ExecuteNodeInIsolationAsync(nodeInstance, input, context, timeout);

    return await nodeInstance.ExecuteAsync(input, context);
}

Leveraging the .NET Thread Pool

The .NET Thread Pool is incredibly good at its job, but it needs the engine to be a 'good citizen'. By being truly asynchronous, we allow the .NET runtime to:

Dynamically scale the number of threads based on CPU load
Optimize task scheduling to keep CPU caches warm
Avoid context-switching overhead that comes with excessive multi-threading

The Results

By combining non-blocking I/O with granular concurrency control, Vyshyvanka can scale horizontally. Because our execution state is persisted separately from the workflow definition, you can spin up multiple engine instances connected to the same database. Your throughput is limited by your infrastructure, not by a single process.

Performance is a journey of constant refinement. By respecting the asynchronous nature of .NET, isolating execution contexts, and avoiding thread-blocking patterns, we have built an engine that is as fast as it is flexible.

In the next part, we will discuss Part 13: Deployment Strategies - Orchestrating Vyshyvanka with .NET Aspire. Stay tuned!

Check out the project source code here: https://github.com/homolibere/Vyshyvanka

Part 11: Testing Strategies - Guaranteeing Rock-Solid Workflows

Nick — Mon, 22 Jun 2026 07:01:00 +0000

In the world of workflow automation, the cost of failure is high. A bug in a workflow can lead to lost data, broken integrations, or halted business processes. To prevent this, we have built a comprehensive testing strategy for Vyshyvanka that covers every layer — from isolated unit tests to full API integration tests.

The Philosophy: Testable by Design

Before we write a single test, we ensure our code is testable. We accomplish this by:

Injecting dependencies (like HttpClient or ICredentialProvider) into constructors
Using interfaces everywhere so we can substitute real implementations in tests
Keeping node logic pure — given input and configuration, produce output

This simple architectural choice allows us to easily swap real services for test doubles.

Our Testing Stack

Tool	Purpose
xUnit	Test framework with async support
AwesomeAssertions	Fluent assertion library (`.Should().Be(...)`)
NSubstitute	Interface mocking (`Substitute.For<IService>()`)
CsCheck	Property-based testing for validation and serialization
bUnit	Blazor component testing
WebApplicationFactory	Full API integration tests

Example: Testing a Node

Let us look at how we test the HttpRequestNode. We do not make real network calls — we inject a custom MockHttpHandler that returns preconfigured responses:

public class HttpRequestNodeTests
{
    private static ExecutionContext CreateContext() =>
        new(Guid.NewGuid(), Guid.NewGuid(), NullCredentialProvider.Instance);

    private static HttpRequestNode CreateNodeWithHandler(HttpMessageHandler handler)
    {
        var client = new HttpClient(handler);
        return new HttpRequestNode(client);
    }

    [Fact]
    public async Task WhenGetRequestSucceedsThenReturnsSuccessWithResponseData()
    {
        var handler = new MockHttpHandler(new HttpResponseMessage(HttpStatusCode.OK)
        {
            Content = new StringContent(
                """{"message":"hello"}""",
                Encoding.UTF8,
                "application/json")
        });
        var sut = CreateNodeWithHandler(handler);
        var config = JsonSerializer.SerializeToElement(new
        {
            url = "https://api.example.com/data",
            method = "GET"
        });
        var input = new NodeInput { Data = default, Configuration = config };
        var context = CreateContext();

        var result = await sut.ExecuteAsync(input, context);

        result.Success.Should().BeTrue();
        result.Data.GetProperty("statusCode").GetInt32().Should().Be(200);
    }
}

Key patterns here:

MockHttpHandler is a custom HttpMessageHandler that captures requests and returns preset responses.
NullCredentialProvider.Instance provides a no-op credential provider for tests that don't need auth.
Configuration is passed as JsonElement — matching exactly how the engine delivers it.
Assertions use AwesomeAssertions' fluent syntax.

Mocking with NSubstitute

For services behind interfaces, we use NSubstitute. Here is how we test the PluginLoadingService:

public class PluginLoadingServiceTests
{
    private readonly IPluginLoader _pluginLoader = Substitute.For<IPluginLoader>();
    private readonly IPluginValidator _pluginValidator = Substitute.For<IPluginValidator>();
    private readonly INodeRegistry _nodeRegistry = Substitute.For<INodeRegistry>();
    private readonly IPackageCache _packageCache = Substitute.For<IPackageCache>();
    private readonly PluginLoadingService _sut;

    public PluginLoadingServiceTests()
    {
        _sut = new PluginLoadingService(
            _pluginLoader, _pluginValidator, _nodeRegistry, _packageCache);
    }

    [Fact]
    public async Task WhenPluginLoadsSuccessfullyThenRegistersNodes()
    {
        var assembly = typeof(PluginLoadingServiceTests).Assembly;
        _pluginLoader.TryLoadAssembly(Arg.Any<string>())
            .Returns(assembly);
        _pluginValidator.ValidatePlugin(assembly)
            .Returns(new PluginValidationResult { IsValid = true });

        var result = await _sut.LoadAndValidatePluginsAsync(
            "test-pkg", "1.0.0", "/install/path");

        result.Failure.Should().BeNull();
        _nodeRegistry.Received(1).RegisterFromAssembly(assembly);
    }
}

NSubstitute gives us:

Substitute.For<T>() — creates a test double for any interface
Arg.Any<T>() — matches any argument
.Returns(value) — configures return values
.Received(n) — verifies a method was called n times

Property-Based Testing with CsCheck

For logic that should hold true for all inputs (not just hand-picked examples), we use CsCheck:

[Fact]
public void WhenSerializedThenDeserializationRoundTrips()
{
    Gen.String.Sample(original =>
    {
        var json = JsonSerializer.Serialize(original);
        var result = JsonSerializer.Deserialize<string>(json);
        Assert.Equal(original, result);
    });
}

[Fact]
public void WhenWorkflowIdGeneratedThenAlwaysValid()
{
    Gen.Guid.Sample(id =>
    {
        id.Should().NotBe(Guid.Empty);
        Guid.TryParse(id.ToString(), out _).Should().BeTrue();
    });
}

CsCheck generates hundreds of random inputs and verifies your invariants hold for all of them. We use this extensively for:

Serialization round-trips
Expression evaluator edge cases
Validation logic completeness

Integration Tests

For end-to-end API testing, we use WebApplicationFactory:

public class ExecutionApiTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly HttpClient _client;

    public ExecutionApiTests(WebApplicationFactory<Program> factory)
    {
        _client = factory.CreateClient();
    }

    [Fact]
    public async Task WhenWorkflowNotFoundThenReturns404()
    {
        var request = new { workflowId = Guid.NewGuid() };
        var response = await _client.PostAsJsonAsync("/api/execution", request);

        response.StatusCode.Should().Be(HttpStatusCode.NotFound);
    }
}

This spins up the full ASP.NET Core pipeline in-process — middleware, controllers, DI, database — giving us confidence that the entire stack works together.

Test Organization

All tests live in Vyshyvanka.Tests/, organized by type:

tests/Vyshyvanka.Tests/
├── Unit/                  # Isolated tests, no I/O
│   ├── Nodes/            # Node-specific tests
│   ├── Components/       # Blazor component tests (bUnit)
│   └── ...
├── Property/             # CsCheck property-based tests
├── Integration/          # WebApplicationFactory tests
│   └── Fixtures/         # Shared test fixtures
└── E2E/                  # End-to-end scenario tests

Test Naming Convention

We follow the pattern When{Condition}Then{ExpectedResult}:

WhenWorkflowHasNoTriggerThenValidationFails()
WhenGetRequestSucceedsThenReturnsSuccessWithResponseData()
WhenPluginValidationFailsThenReturnsError()

This makes test output self-documenting — you can read the test names as a specification of the system's behavior.

The Benefits

Speed: Unit tests run in milliseconds. We can run the full suite on every commit.
Confidence: By mocking external dependencies, we verify our code's logic in isolation.
Documentation: Tests are the ultimate specification — they show exactly how every component behaves under specific conditions.
Regression Protection: Property-based tests catch edge cases that hand-written tests miss.

Testing is not a chore; it is a safety net. By making our nodes modular, injecting our dependencies, and rigorously testing every layer, we ensure that Vyshyvanka remains as reliable as the systems it automates.

In the next part, we will discuss Part 12: Performance Optimization - High-throughput processing and concurrency. Stay tuned!

Check out the project source code here: https://github.com/homolibere/Vyshyvanka

Part 10: Plugin System Architecture - Extensibility by Design

Nick — Fri, 19 Jun 2026 08:02:00 +0000

Our workflow engine is designed to be more than just a pre-defined set of nodes. We recognize that every business, every API, and every integration is unique. That is why we built Vyshyvanka around a robust, assembly-based plugin architecture that allows you to extend the engine without touching the core codebase.

The Foundation: Assembly Loading

At the heart of our extensibility model is .NET's AssemblyLoadContext. When the engine starts, the PluginLoader scans a designated plugin directory for compiled .dll files. Each plugin gets its own collectible PluginLoadContext, which provides full isolation from the core application — preventing version conflicts between your dependencies and the engine's dependencies.

internal class PluginLoadContext : AssemblyLoadContext
{
    private readonly AssemblyDependencyResolver _resolver;

    public PluginLoadContext(string pluginPath) : base(isCollectible: true)
    {
        _resolver = new AssemblyDependencyResolver(pluginPath);
    }

    protected override Assembly? Load(AssemblyName assemblyName)
    {
        // Try to resolve from plugin directory first
        var assemblyPath = _resolver.ResolveAssemblyToPath(assemblyName);
        if (assemblyPath is not null)
            return LoadFromAssemblyPath(assemblyPath);

        // Fall back to default context for shared assemblies (like Vyshyvanka.Core)
        return null;
    }
}

The isCollectible: true flag means plugins can be unloaded at runtime — enabling hot-reload scenarios and safe removal of installed packages.

Declaring Plugins

Each plugin is identified by a PluginAttribute on the assembly. This tells the engine who you are, what version you are on, and provides discovery metadata:

// PluginInfo.cs
using Vyshyvanka.Core.Interfaces;

[assembly: Plugin(
    "vyshyvanka.plugin.httpclient",
    Name = "Advanced HTTP Client",
    Version = "1.0.0",
    Description = "Advanced HTTP client nodes with retry, polling, and batch request capabilities.",
    Author = "Vyshyvanka")]

If an assembly does not have this attribute, the loader skips it silently — only intentional Vyshyvanka plugins get registered.

Creating Custom Nodes

The power of the system lies in how we define nodes. A node class inherits from BasePluginNode and is decorated with attributes that describe its UI representation and configuration schema:

[NodeDefinition(
    Name = "GraphQL Request",
    Description = "Execute GraphQL queries and mutations against a GraphQL endpoint",
    Icon = "fa-solid fa-diagram-project")]
[NodeInput("input", DisplayName = "Input")]
[NodeOutput("output", DisplayName = "Response", Type = PortType.Object)]
[ConfigurationProperty("endpoint", "string", Description = "GraphQL endpoint URL", IsRequired = true)]
[ConfigurationProperty("query", "string", Description = "GraphQL query or mutation string", IsRequired = true)]
[ConfigurationProperty("variables", "object", Description = "Query variables as key-value pairs")]
[ConfigurationProperty("headers", "object", Description = "Additional HTTP headers")]
[ConfigurationProperty("timeout", "number", Description = "Request timeout in seconds (default: 30)")]
public class GraphQLNode : BasePluginNode
{
    public override string Type => "graphql-request";
    public override NodeCategory Category => NodeCategory.Action;

    public override async Task<NodeOutput> ExecuteAsync(NodeInput input, IExecutionContext context)
    {
        var endpoint = GetRequiredConfigValue<string>(input, "endpoint");
        var query = GetRequiredConfigValue<string>(input, "query");
        var variables = GetConfigValue<Dictionary<string, object>>(input, "variables");
        var timeoutSeconds = GetConfigValue<int?>(input, "timeout") ?? 30;

        // ... execute the GraphQL request ...

        return SuccessOutput(responseData);
    }
}

Notice that [ConfigurationProperty] attributes are placed on the class itself (not on individual properties). Configuration values are accessed at runtime through the GetConfigValue<T>() and GetRequiredConfigValue<T>() helper methods inherited from the base class. This design means the engine and Designer UI can discover the configuration schema via reflection without instantiating the node.

Plugin Validation

Before a plugin is registered, the PluginValidator checks it for correctness:

Does it have the required [Plugin] attribute?
Do its node types properly implement INode?
Are there any dependency conflicts?

If validation fails, the plugin is rejected but the engine continues operating. You get a clear error in the logs telling you exactly what went wrong.

Package Management

Beyond dropping DLLs into a directory, Vyshyvanka has a full NuGet-based package management system. The NuGetPackageManager orchestrates the lifecycle:

PackageSearchService — Searches configured NuGet sources, resolves versions, checks for updates.
PluginLoadingService — Loads plugin assemblies, validates them, and registers their node types with the NodeRegistry.
NuGetPackageManager — Orchestrates install/update/uninstall using the above services.

This means you can install plugins from private NuGet feeds, manage versions centrally, and update plugins without restarting the engine.

Why This Design?

Strong Typing: By leveraging C# attributes, we automatically generate the UI schema for your nodes. When you add a new [ConfigurationProperty], it appears in the Designer without writing frontend code.
Isolation: Each plugin runs in its own AssemblyLoadContext. If a plugin fails to load or crashes during execution, the rest of the engine remains operational. Plugin nodes are executed through IPluginHost with a timeout wrapper.
Discoverability: The NodeRegistry automatically picks up all INode implementations from loaded plugin assemblies, making them available in the Designer immediately.
Hot Unload: Because load contexts are collectible, you can uninstall a plugin at runtime. The GC reclaims the memory once all references are released.

Exploring Real Examples

If you look into our ./plugins/ directory, you can see this in action:

Vyshyvanka.Plugin.AdvancedHttp — HTTP retry with exponential backoff, HTTP polling with success/failure conditions, batch requests with concurrency control, and GraphQL.
Vyshyvanka.Plugin.GitLab — Full GitLab integration: issues, merge requests, pipelines, releases, files, tags, and webhook triggers.
Vyshyvanka.Plugin.Jira — Jira issues, comments, search (JQL), users, and versions.
Vyshyvanka.Plugin.Tmplt — A starter template for building your own plugin.

Getting Started with Your Own Plugin

Create a new class library targeting the same .NET version.
Add a reference to Vyshyvanka.Core (the only allowed dependency from core).
Add your PluginInfo.cs with [assembly: Plugin(...)].
Create node classes inheriting BasePluginNode (or implement INode directly).
Decorate with [NodeDefinition] and [ConfigurationProperty] attributes.
Build, and either drop the DLL into the plugins directory or publish as a NuGet package.

Building for extensibility ensures that as your business needs evolve, your automation platform evolves with you.

In the next part, we will discuss Part 11: Testing Strategies - How to guarantee your workflows are rock-solid. Stay tuned!

Check out the project source code here: https://github.com/homolibere/Vyshyvanka

Part 9: Security First - Credentials, Auth, and Secrets Management

Nick — Thu, 18 Jun 2026 08:01:00 +0000

Building a workflow engine that interacts with external APIs, databases, and internal systems means you are constantly handling sensitive data. If you get security wrong here, the consequences are severe. Today, we are discussing how we handle credentials, authentication, and secrets management in Vyshyvanka.

The Problem: Where do secrets live?

The biggest mistake developers make when building automation tools is hard-coding credentials. Whether it is an API key in a config file or a database password in an environment variable, these secrets eventually leak. We needed a way to manage secrets that is both developer-friendly and secure enough for production environments.

The Credential Store

In Vyshyvanka, we do not store raw secrets in the workflow definition. Instead, we use a dedicated Credential Store. When you add a new service integration to your workflow, you create a Credential object through the Credential Manager UI. This object holds the encrypted access data for that service.

Each node that needs authentication is assigned a CredentialId in its configuration. At runtime, the engine resolves that reference through the ICredentialProvider, decrypts the credential in-memory, and provides it to the node instance. The raw secrets never appear in workflow JSON, API responses, or execution logs.

// How a node receives its credential at execution time
var input = new NodeInput
{
    Data = inputData,
    Configuration = evaluatedConfig,
    CredentialId = node.CredentialId  // Reference, not the actual secret
};

Three Storage Backends

We support three credential storage providers, configurable via appsettings.json:

Provider	Config Value	How Secrets Are Stored
Built-in	`BuiltIn`	AES-256 encrypted in the database
HashiCorp Vault	`HashiCorpVault`	Vault KV v2 secret engine
OpenBao	`OpenBao`	OpenBao KV v2 secret engine

All three share the same ICredentialService interface and CredentialValidator logic. The choice of backend is transparent to the rest of the system — nodes never know where their credentials are stored.

Encryption at Rest (Built-in Provider)

For the built-in provider, we use AesCredentialEncryption with AES-256. The master encryption key is managed via environment variables — never stored in appsettings.json or committed to source control.

public sealed class AesCredentialEncryption : ICredentialEncryption
{
    // Encrypts credential data before DB persistence
    // Decrypts on-demand when a node needs access
}

Even if a database backup is compromised, the actual credentials remain encrypted and unusable without the master key.

External Secrets Managers (Vault / OpenBao)

For enterprises that already manage secrets centrally, the VaultCredentialService delegates all secret storage to HashiCorp Vault or OpenBao. Metadata (name, type, associations) stays in the database, but the actual sensitive values live in the vault's KV v2 engine.

This gives you:

Centralized secret rotation without touching Vyshyvanka
Audit trails from the vault itself
Integration with existing enterprise key management

Authentication Providers

Vyshyvanka supports four authentication strategies, selectable at deployment time:

Provider	Session Tokens	Login Flow
Built-in	Local JWT	Username/password via API
Keycloak	External OIDC	Redirect to Keycloak
Authentik	External OIDC	Redirect to Authentik
LDAP	Local JWT	Verify against directory

For OIDC providers, the API validates external tokens and an OidcClaimsTransformation middleware provisions local users on first login. For LDAP, the LdapAuthenticationService verifies credentials against the directory server.

Additionally, API key authentication (X-API-Key header) is always available regardless of the primary provider — useful for CI/CD integrations and automated workflow triggers.

Node-Level Auth Strategies

Our node architecture supports various authentication strategies per credential type:

Basic Auth: Username/password for legacy services
Bearer Tokens: The standard for most modern REST APIs
API Keys: Header or query parameter based
Custom Headers: For services with non-standard auth schemes

Each node that requires credentials declares this with the [RequiresCredential] attribute, and the Designer UI automatically shows the credential picker for that node.

Security Rules We Enforce

Always:

Encrypt credentials at rest (AES-256 or delegate to Vault/OpenBao)
Validate resource ownership via ICurrentUserService before any operation
Use parameterized queries for all database operations
Sanitize user input in expressions to prevent injection

Never:

Return credential values in any API response
Log credentials or sensitive data at any log level
Allow cross-user workflow access without explicit sharing
Store Vault/OpenBao tokens in plain text in config files

Best Practices

Rotate your keys: The credential store allows you to update a secret without modifying workflow logic. The CredentialId reference stays the same.
Use scoped permissions: If a service supports it, create API keys with minimum required permissions.
Choose the right backend: Use Vault/OpenBao for production environments where compliance and audit trails matter. The built-in provider works well for development and small deployments.

Security is not a feature you add at the end; it is the foundation on which everything else is built.

In the next part, we will discuss Part 10: Plugin System Architecture - Extensibility by Design. Stay tuned!

Check out the project source code here: https://github.com/homolibere/Vyshyvanka

Part 8: Persistence and State - EF Core, Migrations, and Reliability

Nick — Wed, 17 Jun 2026 08:01:00 +0000

In the last part, we looked at how expressions make your workflows dynamic. Today, we are discussing the backbone of any production-ready system: Persistence. How do we keep your workflow data, execution history, and node states safe, even if the server crashes or restarts?

EF Core: Our Reliable Partner

Vyshyvanka uses Entity Framework Core (EF Core) as the primary abstraction for database interaction. It allows us to work with our domain entities in a type-safe, object-oriented way while maintaining the flexibility to target different database backends.

For development, we default to SQLite because it makes setting up local testing environments trivial — no external services, no Docker containers, just a file. For production, we support PostgreSQL, which gives us the robustness, scalability, and feature set required for high-volume automation tasks.

The switch between backends is handled at startup via configuration and .NET Aspire service wiring, so the same application code works seamlessly against both.

The Migration Workflow

One of the most important rules in our development culture is this: Never use EnsureCreatedAsync() in production.

While it is tempting for quick prototyping, relying on auto-generation for production schemas is a recipe for disaster. We strictly use EF Core Migrations. This approach provides a version-controlled history of your database schema, ensuring that deployments are predictable and that we can roll back if something goes wrong.

Our command for adding a migration is standardized:

dotnet ef migrations add <Name> \
  --project src/Vyshyvanka.Engine \
  --startup-project src/Vyshyvanka.Api \
  --output-dir Persistence/Migrations

At startup, the application automatically applies any pending migrations with MigrateAsync(). This ensures that every deployment brings the schema up to date without manual intervention.

Separation of Concerns

Our persistence layer follows a clean separation:

Location	Purpose
`Vyshyvanka.Engine/Persistence/VyshyvankaDbContext.cs`	The EF Core DbContext
`Vyshyvanka.Engine/Persistence/Entities/`	Entity classes (DB table mappings)
`Vyshyvanka.Engine/Persistence/Migrations/`	Auto-generated migration files
`Vyshyvanka.Core/Interfaces/`	Repository interfaces
`Vyshyvanka.Engine/Persistence/`	Repository implementations

This ensures that the domain layer (Core) never depends on EF Core or any specific database technology. The engine provides the implementation details.

State Separation

We persist the workflow state (the graph structure — nodes, connections, configuration) and the execution state (the runtime status of every node during a run) separately. This separation allows us to perform high-frequency updates on the execution state without modifying the workflow definition itself.

When an execution transitions states, we use database transactions to ensure atomicity:

The node execution result is saved.
The overall execution status is updated.
Terminal states (Completed, Failed, Cancelled) are final — no further writes allowed.

This prevents zombie executions or partially processed data from corrupting your results.

Async All the Way Down

Every repository method follows our async-first pattern with CancellationToken:

public async Task<Workflow?> GetByIdAsync(Guid id, CancellationToken ct)
{
    return await _context.Workflows
        .Include(w => w.Nodes)
        .Include(w => w.Connections)
        .FirstOrDefaultAsync(w => w.Id == id, ct);
}

This ensures that database I/O never blocks threads, keeping the engine responsive even under heavy load.

Testing Our Persistence

Because we use EF Core, we can leverage lightweight in-memory providers to write unit tests for our data access logic without needing a real database:

[Fact]
public async Task WhenWorkflowSavedThenCanBeRetrieved()
{
    var options = new DbContextOptionsBuilder<VyshyvankaDbContext>()
        .UseInMemoryDatabase(databaseName: Guid.NewGuid().ToString())
        .Options;

    await using var context = new VyshyvankaDbContext(options);
    var repository = new WorkflowRepository(context);

    var workflow = CreateTestWorkflow();
    await repository.SaveAsync(workflow, CancellationToken.None);
    var retrieved = await repository.GetByIdAsync(workflow.Id, CancellationToken.None);

    retrieved.Should().NotBeNull();
    retrieved!.Nodes.Should().HaveCount(workflow.Nodes.Count);
}

For integration tests, we use WebApplicationFactory with a real SQLite database to test the full API-to-database path.

Credential Storage

Credentials get special treatment in our persistence layer. The CredentialEntity stores encrypted data — never plain text. The encryption key is managed externally (environment variables or a secrets manager). Even if someone gets access to the database, the credential values remain protected by AES-256 encryption.

Persistence is the quiet backbone of Vyshyvanka. By respecting migrations, separating concerns, and testing at every level, we ensure that your workflow data is always safe, consistent, and recoverable.

In the next part, we will discuss Part 9: Security First - Credentials, Authentication, and Secrets Management. Stay tuned!

Check out the project source code here: https://github.com/homolibere/Vyshyvanka

Part 7: Expression Language Syntax - Powering Logic in Nodes

Nick — Tue, 16 Jun 2026 08:01:00 +0000

In our previous parts, we looked at how Vyshyvanka executes tasks and handles failures. But what makes a workflow truly dynamic? The answer is our Expression Language. Today, we are going to look at how we turn static node configuration into dynamic logic that adapts to data at runtime.

Why Expressions?

If nodes were static, workflows would be useless for anything beyond fixed sequences. You would need to hard-code every email address, every database query value, and every condition. That does not work in the real world. You need your workflow to respond to incoming data — like a dynamic ID from a webhook or a calculated value from a previous database query.

The Double-Brace Syntax

We use a simple, double-brace syntax to reference data. If you have ever used Jinja2 or Liquid, you will feel right at home.

Pattern	Resolves To
`{{ nodes.<nodeId>.data }}`	Full JSON output of a previous node
`{{ nodes.<nodeId>.data.prop }}`	Nested property access
`{{ nodes.<nodeId>.data.items[0].name }}`	Array index + property
`{{ variables.executionId }}`	Current execution ID
`{{ variables.workflowId }}`	Current workflow ID

The two valid roots are nodes (referencing other node outputs) and variables (execution metadata). Any other root will be rejected at validation time with a clear error message.

How it Works

When the engine pipeline hits a node, it does not just pass the configuration object as-is. It runs an evaluation pass via the ExpressionEvaluator. It uses a compiled regex to find all {{ ... }} placeholders, resolves each path against the IExecutionContext, and replaces the placeholder with the actual value before the node's ExecuteAsync is called.

A key design decision: if the entire configuration value is a single expression (e.g., {{ nodes.api.data }}), the evaluator returns the actual typed value (a JsonElement, an integer, etc.) rather than a string. This means you can pass complex objects between nodes without serialization loss. When expressions are embedded in a longer string, they are interpolated as strings.

Built-in Functions

Beyond simple path resolution, our expression engine supports a rich library of built-in functions for data transformation directly within expressions:

String functions:

{{ toUpper(nodes.webhook.data.name) }}
{{ toLower(nodes.api.data.email) }}
{{ trim(nodes.form.data.input) }}
{{ replace(nodes.api.data.url, "http://", "https://") }}
{{ concat(nodes.user.data.firstName, " ", nodes.user.data.lastName) }}
{{ substring(nodes.api.data.code, 0, 3) }}

Date/time functions:

{{ now() }}
{{ utcNow() }}
{{ formatDate(nodes.db.data.createdAt, "yyyy-MM-dd") }}
{{ addDays(nodes.schedule.data.dueDate, 7) }}

Math functions:

{{ round(nodes.calc.data.total, 2) }}
{{ abs(nodes.diff.data.value) }}
{{ min(nodes.a.data.x, nodes.b.data.y) }}

Type conversion and logic:

{{ toString(nodes.api.data.count) }}
{{ toNumber(nodes.form.data.quantity) }}
{{ coalesce(nodes.api.data.nickname, nodes.api.data.name, "Anonymous") }}
{{ iif(nodes.check.data.isActive, "enabled", "disabled") }}

These functions are strictly data-access and transformation utilities — they cannot perform I/O, call external services, or modify state. Complex logic belongs in Logic Nodes or Code Nodes, not inside expressions.

Validation

Before a workflow executes, you can validate expressions with the Validate method. It checks:

That expression syntax is well-formed (matching {{ }} braces)
That paths start with a valid root (nodes or variables)
That paths are complete (not just {{ nodes }} without a node ID)

var result = evaluator.Validate("{{ nodes.api.data.items[0].id }}");
// result.IsValid == true

var badResult = evaluator.Validate("{{ credentials.apiKey }}");
// result.IsValid == false
// Error: "Unknown expression root 'credentials'. Expected 'nodes' or 'variables'"

Security First

Dynamic expression evaluation is a dangerous tool if not handled correctly. A classic vulnerability in workflow engines is allowing malicious users to execute arbitrary code via expression injection.

We treat this with extreme care:

Sandboxed Evaluation: We do not use eval() or equivalent code execution. We use a strictly controlled property resolver that can only access the execution context through well-defined paths.
Controlled Function Set: The available functions are a fixed, curated set compiled into the engine. Users cannot register custom functions or call arbitrary methods.
Sanitization: All values resolved from the expression engine are treated as untrusted input. Before these values are passed to nodes (especially those performing database queries or shell commands), they are sanitized or parameterized.
No Side Effects: Expression functions are pure — they cannot modify the execution context, perform network calls, or write to disk.

Building Dynamic Workflows

This syntax is how you build a real workflow. Imagine a sequence where:

A WebhookTrigger receives an order payload.
An HttpRequest node calls an external API using {{ nodes.webhook.data.orderId }}.
A Switch node checks the result with {{ nodes.http.data.status }}.
An EmailSend node formats a message with {{ concat("Order ", nodes.webhook.data.orderId, " is ", toLower(nodes.http.data.status)) }}.

Every step references the output of a previous step dynamically. The workflow adapts to whatever data flows through it at runtime.

In the next part, we will discuss Part 8: Persistence and State - EF Core, Migrations, and Reliability. Stay tuned!

Check out the project source code here: https://github.com/homolibere/Vyshyvanka

Part 6: Engine Internals - The Execution Pipeline

Nick — Mon, 15 Jun 2026 08:01:00 +0000

We have seen how you design a workflow and how the domain model keeps it strictly type-safe. Today, we are peeling back the most complex layer of Vyshyvanka: The Execution Pipeline. This is where the graph you drew in the browser becomes a series of actual operations executing on the server.

From Graph to Execution

When you hit 'Run', the engine doesn't just start running nodes randomly. It first performs a topological sort on your directed graph using BuildExecutionLevels. This groups nodes into execution levels - nodes at the same level have no dependencies on each other and can run in parallel, while each level depends only on previous levels.

If Node B needs the output of Node A, the topological sort guarantees Node A finishes first. If there's a circular dependency in your graph, our validator catches it before it ever hits the engine.

The Life Cycle of an Execution

Every run is an immutable record that transitions through a strict state machine:

Pending ──→ Running ──→ Completed
  │            │
  │            ├──→ Failed
  │            │
  └──→ Cancelled ←──┘

Pending: The trigger has fired, and we have initialized the execution context.
Running: We start processing the sorted levels of nodes.
Terminal States: Once a workflow hits Completed, Failed, or Cancelled, that's it. No further transitions allowed.

We don't allow mutable state transitions back from a terminal state. This ensures that every execution record is an audit-ready snapshot that you can trust.

The Pipeline at Work

The pipeline itself is fully asynchronous. We leverage .NET's async/await throughout the entire chain, passing a CancellationToken into every method. If a user cancels a workflow or the server initiates a graceful shutdown, every single node in the pipeline receives that signal and halts immediately.

Here is a simplified view of the core execution loop:

public async Task<ExecutionResult> ExecuteAsync(
    Workflow workflow,
    IExecutionContext context,
    CancellationToken cancellationToken = default)
{
    var executionLevels = BuildExecutionLevels(workflow);
    var maxParallelism = GetEffectiveMaxParallelism(workflow.Settings.MaxDegreeOfParallelism);

    foreach (var level in executionLevels)
    {
        cancellationToken.ThrowIfCancellationRequested();

        var levelResults = await ExecuteLevelWithThrottlingAsync(
            workflow, level, context, nodeResults, maxParallelism, cancellationToken);

        // Check StopOnFirstError policy
        if (workflow.Settings.ErrorHandling == ErrorHandlingMode.StopOnFirstError)
        {
            var failedResult = levelResults.FirstOrDefault(r => !r.Success);
            if (failedResult is not null) return BuildResult(/* ... */);
        }
    }
    // ...
}

Inside the pipeline, each node goes through several stages:

Input Gathering: We collect outputs from upstream nodes via connection mapping. Multi-input nodes receive a merged JSON object keyed by target port name.
Expression Evaluation: All {{ nodes.someNode.data }} expressions in the node configuration are resolved in real-time from the execution context before the node runs.
Node Execution: We invoke ExecuteAsync on the node instance. Since all nodes inherit from our base classes (BaseTriggerNode, BaseActionNode, BaseLogicNode), the engine handles them uniformly regardless of what they actually do.
Output Storage: Successful node outputs are stored in the context, ready for downstream nodes to reference.

Parallel Branch Execution

Nodes at the same execution level run in parallel, throttled by a SemaphoreSlim:

private async Task<NodeExecutionResult[]> ExecuteLevelWithThrottlingAsync(
    Workflow workflow, List<string> level, IExecutionContext context,
    ConcurrentBag<NodeExecutionResult> nodeResults, int maxParallelism,
    CancellationToken cancellationToken)
{
    using var semaphore = new SemaphoreSlim(maxParallelism, maxParallelism);

    var tasks = level.Select(async nodeId =>
    {
        await semaphore.WaitAsync(cancellationToken);
        try { return await ExecuteNodeInWorkflowAsync(workflow, nodeId, context, nodeResults, cancellationToken); }
        finally { semaphore.Release(); }
    }).ToList();

    return await Task.WhenAll(tasks);
}

The default max parallelism is Environment.ProcessorCount * 2, but you can configure it per workflow.

Handling Failure

What happens when a node fails? The engine supports two error handling modes:

StopOnFirstError: Stops the entire workflow immediately when any node fails.
ContinueOnError: Marks the failed node and continues executing independent branches. Dependent nodes on the failed branch are skipped.

Because we have that immutable execution record, you can see exactly which node caused the issue, what data it received, and the error message — all structured in the NodeExecutionResult list.

Plugin Node Isolation

Plugin nodes (from external assemblies) are executed through IPluginHost.ExecuteNodeInIsolationAsync, which adds an additional timeout layer:

private async Task<NodeOutput> ExecuteNodeInstanceAsync(
    INode nodeInstance, NodeInput input, IExecutionContext context, TimeSpan timeout)
{
    if (_pluginHost is not null && _pluginHost.IsPluginNode(nodeInstance.Type))
        return await _pluginHost.ExecuteNodeInIsolationAsync(nodeInstance, input, context, timeout);

    return await nodeInstance.ExecuteAsync(input, context);
}

This ensures that a misbehaving plugin cannot hang the entire engine.

Why Asynchronous?

We chose async-first because workflow engines are inherently I/O bound. You are constantly waiting for databases, external APIs, and file systems. By using async/await everywhere, we ensure that while one workflow waits for a response, the thread is returned to the pool to serve other workflows. This is how a single engine instance can manage hundreds of concurrent executions without thread pool starvation.

In the next part, we will discuss Part 7: Expression Language Syntax - How dynamic data flows between your nodes. Stay tuned!

Check out the project source code here: https://github.com/homolibere/Vyshyvanka

Part 5: Designing the Designer - Building a Blazor WASM Experience

Nick — Fri, 12 Jun 2026 08:00:00 +0000

In our last deep dive, we talked about the logic and data structures that drive Vyshyvanka. But software isn't just about clean backends; it's about how the user interacts with those systems. Today, we're stepping into the browser to talk about the Vyshyvanka Designer - our Blazor WebAssembly canvas.

Why Blazor WebAssembly?

When we decided to build a visual workflow designer, we had a few options: React, Vue, or maybe a native desktop app. We chose Blazor WebAssembly for a few critical reasons:

Shared Logic: By staying within the .NET ecosystem, we can share domain models and validation logic between our Engine and the Designer. When we update a node definition in the Core, the Designer understands those changes instantly without rewriting types in TypeScript.
Performance: Blazor WASM gives us the performance of a compiled language inside the browser, which is crucial when you're dragging and dropping dozens of nodes or panning around a large workflow.
Developer Velocity: Our team works best in C#. Having a single language for both our ASP.NET Core API and our frontend allows us to move fast without the context switching of a JavaScript-heavy stack.

The Designer Architecture

The Designer isn't one big component; it's a system of decomposed services designed to keep the UI snappy and maintainable:

WorkflowStore: The single source of truth. It holds your workflow data, node definitions, and the 'dirty' flag that tells the UI when you have unsaved changes.
WorkflowEditService: This is the brains of the operation. Whenever you drag a node, add a connection, or delete a step, the EditService handles the business logic. It doesn't worry about rendering; it just worries about state.
WorkflowValidationService: We run validation in the browser as you edit. If you try to connect an 'Object' output to a 'Boolean' input, the UI turns red before you even let go of your mouse.
CanvasStateService: Handles the 'feel' of the application. Panning, zooming, node selection, and undo/redo stacks are managed here.

Communicating with the Engine

We made a hard architectural choice early on: The Designer communicates exclusively via HTTP.

There are no direct WebSocket connections or shared memory paths to the Engine. By forcing all interaction through the WorkflowApiClient, we ensure the Designer remains a pure client. This means we can treat the entire Designer as a standalone application that could be hosted anywhere. It doesn't care if the engine is running on your machine, in a Docker container, or in the cloud—as long as it can hit the API, it works.

Component Design Rules

To keep our UI code clean, we enforce strict rules:

No @code blocks in .razor files: All logic lives in Name.razor.cs partial classes.
Injection over @inject: We use [Inject] attributes in our code-behind to keep the markup clean and the dependencies explicit.
One Component, Three Files: Every visual piece follows a Name.razor, Name.razor.cs, and Name.razor.css pattern. It keeps our styles isolated and our logic readable.

The Goal: Real-Time Clarity

The goal of the Designer isn't just to look good; it's to provide real-time clarity. You should know exactly what your workflow is doing at every moment. By integrating our validation service directly into the canvas, we turn the design phase into an active conversation between you and the system.

Building a visual editor in Blazor was an adventure, but the results—a type-safe, performant, and deeply integrated experience—made it all worth it.

In the next part, we'll look at the execution engine internals: The Pipeline. We'll explain how we resolve the graph, manage node execution order, and handle the state machine from 'Pending' to 'Completed'. Stay tuned!

Check out the project source code here: https://github.com/homolibere/Vyshyvanka

Part 4: The Domain Model - Understanding Workflows, Nodes, and Connections

Nick — Thu, 11 Jun 2026 08:00:00 +0000

In our last deep dive, we looked at how Vyshyvanka is put together under the hood. Today, we're zooming in on what actually makes the engine tick: the Domain Model. At the end of the day, Vyshyvanka isn't just a collection of services; it's a system designed to manage a directed graph of operations that we call a Workflow.

The Workflow: A Directed Graph

At its heart, a workflow is a directed graph where nodes represent operations and connections represent the flow of data.

Exactly One Trigger: Every workflow needs a starting point. Whether it's a webhook, a timer, or a manual button press, we enforce that there is exactly one trigger node.
Ownership: Every workflow is owned by a single user, ensuring that permissions and access are managed consistently across the board.

Nodes: The Atomic Operations

Nodes are the building blocks of your automation. We categorize them based on their behavior, which dictates their base class in our engine:

Trigger Nodes: These start the workflow. They have no incoming connections because they define the entry point. Examples include our WebhookTrigger or ScheduleTrigger.
Action Nodes: These do the actual work. Think of them as your worker bees - sending an email, querying a database, or calling an external HTTP API.
Logic Nodes: These are the brains. They allow you to branch execution (If/Switch), create loops, or merge data streams.

When you implement a new node in Vyshyvanka, you simply inherit from the appropriate base class, override the ExecuteAsync method, and register it in the NodeRegistry. The engine takes care of the rest.

Connections and Type Safety

One of the most common sources of bugs in automation platforms is passing incompatible data between steps. We fixed that with a robust Port Type system.

A connection is valid if:

The source port type equals the target port type.
Either port is an 'Any' type, which acts as a wildcard.

Our supported types include Object, Array, String, Number, and Boolean. By enforcing this at the designer level, we ensure that by the time a workflow hits the engine, it's guaranteed to be syntactically and logically sound.

Execution: The Immutable Record

When a workflow runs, we create an Execution record. This is an immutable snapshot of that specific run. Why immutable? Because transparency matters. Once an execution is marked as 'Completed', 'Failed', or 'Cancelled', it is final. You can trace back exactly what data was passed to each node, what the result was, and how the state machine transitioned.

This transition logic is rigid:
Pending -> Running -> (Completed | Failed | Cancelled)

Terminal states are final, and that is a promise the engine keeps. This prevents any accidental state mutations or 'zombie' executions that haunt other automation systems.

Validation Rules

Before a workflow can even be executed, it must pass a battery of checks:

No circular dependencies.
Every node must be reachable from the trigger.
Required properties must be set.
All connections must satisfy port compatibility.

This pre-execution validation means that when you hit 'Run', you can be confident that the workflow isn't going to fail because of a simple wiring mistake.

Why This Matters

By building a strict, type-safe domain model, we've turned what is usually a fragile scripting process into a robust software engineering task. You aren't just "writing a script"; you are defining a formal model that the system understands and can verify.

In the next part, we'll look at the front end of this equation: The Designer. We'll explain how we built a Blazor WebAssembly canvas that allows you to drag, drop, and wire up these nodes in real time. Stay tuned!

Check out the project source code here: https://github.com/homolibere/Vyshyvanka