Where to Find Modly Workflow System Core Files: Architecture and File Paths

The core files for Modly's workflow system reside primarily in src/areas/workflows/ for runtime execution and UI logic, with persistent state management handled by src/shared/stores/workflowsStore.ts.

These modules handle the complete workflow lifecycle in the lightningpixel/modly repository—from loading and validating graph definitions to executing topological sorts and rendering interactive node UIs. The architecture separates concerns between pure execution logic, pre-flight validation, branch resolution semantics, and React-based user interface components.

Execution Engine and Orchestration

The runtime heart of Modly lives in two tightly coupled modules that manage how nodes execute and how data flows between them.

workflowRunStore.ts – Runtime State Management

Located at src/areas/workflows/workflowRunStore.ts, this file implements the execution engine that drives every workflow run. It maintains the RunContext, performs topological sorting to determine execution order, and handles iteration logic for "For-Each" nodes. The store manages calls to external models and processes, updates UI progress state, and maintains the execution stack during complex branch traversals.

When a workflow starts, this module creates the run context, sorts nodes via topoSort, and iterates through the graph while resolving inputs through resolveDataSource calls.

nodeBehaviors.ts – Node Type Semantics

Located at src/areas/workflows/nodeBehaviors.ts, this file registers the behavioral semantics for each node type in the system. It defines whether a node acts as a passthrough, branch starter, scene output, or branch consumer. The module provides critical helper functions like resolveDataSource for input resolution and nearestUpstreamWaits for determining branch membership and preventing illegal merges between incompatible branches.

When you add a new node type, you extend the BEHAVIORS constant in this file to declare how the runner should treat it during graph traversal.

Validation and Persistence Layer

Before execution begins and after workflows are modified, these files ensure data integrity and persistent storage.

preflight.ts – Pre-flight Validation

Located at src/areas/workflows/preflight.ts, this module analyzes workflow graphs before execution begins. It checks for missing inputs, incompatible edge types, and unsupported branch merges that would cause runtime failures. The validateWorkflowPreflight function returns an array of issues that must be resolved before workflowRunStore can safely initiate a run.

Running pre-flight validation prevents expensive runtime errors by catching configuration problems while the user is still in the editor.

workflowsStore.ts – Workflow Persistence

Located at src/shared/stores/workflowsStore.ts, this Zustand-based store manages the loading, saving, and migration of workflow JSON files. It provides the list of available workflows to the UI and handles legacy format migrations when opening older workflow definitions.

This store bridges the gap between the file system and the runtime, supplying workflowRunStore with the graph data needed to begin execution.

User Interface and Interaction Controls

These files handle the React components that users interact with, including the critical pause/resume functionality for human-in-the-loop workflows.

useWaitButton.ts – Pause and Resume Controls

Located at src/areas/workflows/useWaitButton.ts, this React hook exposes the Continue/Retry UI for Wait nodes. When a workflow pauses at a Wait node, this hook renders the button interface and wires user actions to the continueRun method in workflowRunStore.

The hook encapsulates the logic for determining whether a paused run can resume or requires retry, keeping UI state synchronized with the underlying execution engine.

WorkflowsPage.tsx – Main Workflow View

Located at src/areas/workflows/WorkflowsPage.tsx, this component serves as the primary interface for listing available workflows, opening the visual editor, and tying together the various stores. It orchestrates the relationship between the persistence layer (workflowsStore) and the execution layer (workflowRunStore).

nodes/*.tsx – React Flow Node Components

The directory src/areas/workflows/nodes/ contains the React Flow node definitions, including ExtensionNode.tsx, WaitNode.tsx, ForEachNode.tsx, and AddToSceneNode.tsx. These components declare the visual appearance of each node type in the graph editor and pass execution data to the runner via the stores.

Each node component handles its own rendering logic while delegating execution concerns to the core stores, maintaining a clean separation between presentation and business logic.

Working with the Core Files

These examples demonstrate how to interact with Modly's workflow core programmatically.

Starting a Workflow Run

To initiate execution programmatically, combine the persistence store with the run store and pre-flight validation:

import { useWorkflowRunStore } from '@areas/workflows/workflowRunStore'
import { useWorkflowsStore } from '@shared/stores/workflowsStore'

function startWorkflow(id: string) {
  const wf = useWorkflowsStore.getState().workflows.find(w => w.id === id)
  if (!wf) throw new Error('Workflow not found')

  // Validation step – throws if any pre‑flight issue exists
  const issues = validateWorkflowPreflight(wf, getAllExtensions())
  if (issues.length) {
    console.warn('Pre‑flight issues:', issues)
    return
  }

  // Kick off execution; the store handles the whole run lifecycle
  useWorkflowRunStore.getState().runWorkflow(wf)
}

Rendering Wait Node Controls

To render the Continue/Retry button inside a custom Wait node component:

import { useWaitButton } from '@areas/workflows/useWaitButton'

export default function WaitNode({ nodeId }: { nodeId: string }) {
  const button = useWaitButton(nodeId)

  return (
    <div className="wait-node">
      <span>Pause here</span>
      {button}
    </div>
  )
}

Adding Custom Node Behavior

To register a new node type (e.g., filterNode) that behaves as a passthrough, modify src/areas/workflows/nodeBehaviors.ts:

// In src/areas/workflows/nodeBehaviors.ts
const BEHAVIORS = {
  ...BEHAVIORS,
  filterNode: { passthrough: true },
}

The runner will automatically treat filterNode as transparent when walking upstream sources, requiring no additional changes to the execution engine.

Summary

• src/areas/workflows/workflowRunStore.ts contains the execution engine with topological sorting and For-Each iteration logic.
• src/areas/workflows/nodeBehaviors.ts defines how each node type behaves regarding data flow and branch resolution.
• src/areas/workflows/preflight.ts validates workflow configuration before runtime to catch configuration errors early.
• src/areas/workflows/useWaitButton.ts provides the React hook for human-in-the-loop pause and resume functionality.
• src/shared/stores/workflowsStore.ts handles persistence, loading, and migration of workflow files.
• src/areas/workflows/WorkflowsPage.tsx and src/areas/workflows/nodes/*.tsx implement the visual interface for editing and monitoring workflows.

Frequently Asked Questions

Where is the main entry point for executing a workflow in Modly?

The main entry point is the runWorkflow method exported from src/areas/workflows/workflowRunStore.ts. This method accepts a workflow definition and initiates the complete execution lifecycle, including topological sorting, node iteration, and branch handling.

How does Modly validate workflows before running them?

Modly uses src/areas/workflows/preflight.ts to analyze the workflow graph before execution. This module checks for missing inputs, incompatible edge connections, and invalid branch merges, returning a list of issues that must be resolved before the run can proceed.

Which file controls the pause and resume functionality in Modly workflows?

The pause and resume logic is implemented in src/areas/workflows/useWaitButton.ts, which provides a React hook that renders Continue/Retry buttons for Wait nodes. This hook interfaces directly with workflowRunStore to call continueRun when the user resumes execution.

How are workflow files saved and loaded in the Modly system?

Workflow persistence is managed by src/shared/stores/workflowsStore.ts, which handles CRUD operations for workflow JSON files. This store also manages schema migrations for legacy workflow formats and supplies the list of available workflows to the main UI components.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}