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

> Discover Modly workflow system core files in src/areas/workflows/ for runtime and UI logic. Learn about state management in src/shared/stores/workflowsStore.ts. Find Modly core files easily.

- Repository: [lightningpixel/modly](https://github.com/lightningpixel/modly)
- Tags: architecture
- Published: 2026-08-19

---

**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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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:

```typescript
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:

```tsx
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`](https://github.com/lightningpixel/modly/blob/main/src/areas/workflows/nodeBehaviors.ts):

```typescript
// 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`](https://github.com/lightningpixel/modly/blob/main/src/areas/workflows/workflowRunStore.ts)** contains the execution engine with topological sorting and For-Each iteration logic.
- **[`src/areas/workflows/nodeBehaviors.ts`](https://github.com/lightningpixel/modly/blob/main/src/areas/workflows/nodeBehaviors.ts)** defines how each node type behaves regarding data flow and branch resolution.
- **[`src/areas/workflows/preflight.ts`](https://github.com/lightningpixel/modly/blob/main/src/areas/workflows/preflight.ts)** validates workflow configuration before runtime to catch configuration errors early.
- **[`src/areas/workflows/useWaitButton.ts`](https://github.com/lightningpixel/modly/blob/main/src/areas/workflows/useWaitButton.ts)** provides the React hook for human-in-the-loop pause and resume functionality.
- **[`src/shared/stores/workflowsStore.ts`](https://github.com/lightningpixel/modly/blob/main/src/shared/stores/workflowsStore.ts)** handles persistence, loading, and migration of workflow files.
- **[`src/areas/workflows/WorkflowsPage.tsx`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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.