Modly Workflow JSON Structure: Complete Schema and Field Reference

A Modly workflow is stored as a plain JSON object that conforms to the Workflow interface, containing metadata fields and two primary collections—nodes (WFNode[]) and edges (WFEdge[])—that define the visual execution graph.

The lightningpixel/modly repository uses a React-Flow-based visual editor where workflows are serialized to JSON for persistence and version control. Understanding the Modly workflow JSON structure is essential for importing, exporting, or programmatically generating automation pipelines that the runtime can execute.

Core Workflow Schema

The root object follows the Workflow interface declared in src/shared/types/electron.d.ts. It balances descriptive metadata with the structural data required to render the node graph.

Required Metadata Fields

Every workflow must include these top-level properties:

• id: Unique string identifier for the workflow
• name: Human-readable title displayed in the UI
• description: Optional longer explanation of the workflow's purpose
• nodes: Array of WFNode objects representing extension instances
• edges: Array of WFEdge objects defining connections between nodes
• createdAt: ISO-8601 timestamp of creation
• updatedAt: ISO-8601 timestamp of last modification

Organization and Bookmarking Fields

Optional fields control how the workflow appears in the browser:

• folder: String specifying the folder name; omit for root placement
• bookmarked: Boolean flag; when true, the workflow appears in the Bookmarks section

Node Structure (WFNode)

Each element in the nodes array implements the WFNode interface, mapping directly to React-Flow's node specification while adding Modly-specific runtime data.

Visual Positioning and Identity

The visual representation relies on:

• id: Unique node identifier referenced by edge source and target fields
• type: String identifying the node type, typically matching the extension's entry point
• position: Object with x and y number coordinates for canvas placement
• parentId: Optional string for grouping nodes into sub-flows
• extent: Optional string 'parent' restricting movement within group boundaries
• width and height: Optional numbers defining group node dimensions
• style: Optional record for CSS overrides

Runtime Configuration (WFNodeData)

The data field contains a WFNodeData object with execution parameters:

• extensionId: String linking to the specific extension implementation
• enabled: Boolean flag controlling whether the node executes during a run
• params: Free-form object storing extension-specific configuration values

Edge Structure (WFEdge)

Connections between nodes follow the WFEdge interface:

• id: Unique edge identifier
• source: String ID of the originating node
• target: String ID of the terminating node
• sourceHandle: Optional string or null specifying the output slot
• targetHandle: Optional string or null specifying the input slot

Complete Modly Workflow JSON Example

{
  "id": "wf-01",
  "name": "Generate Hero",
  "description": "Creates a hero character mesh from a prompt",
  "folder": "Demo",
  "bookmarked": true,
  "nodes": [
    {
      "id": "node-1",
      "type": "text-prompt",
      "position": { "x": 0, "y": 0 },
      "data": {
        "extensionId": "ext-text-prompt",
        "enabled": true,
        "params": { "prompt": "A heroic knight in armor" }
      }
    },
    {
      "id": "node-2",
      "type": "mesh-generator",
      "position": { "x": 300, "y": 0 },
      "data": {
        "extensionId": "ext-mesh-gen",
        "enabled": true,
        "params": { "size": 1.0 }
      }
    }
  ],
  "edges": [
    {
      "id": "edge-1",
      "source": "node-1",
      "target": "node-2",
      "sourceHandle": null,
      "targetHandle": null
    }
  ],
  "createdAt": "2024-01-15T12:00:00Z",
  "updatedAt": "2024-01-20T09:34:21Z"
}

This example demonstrates a workflow with two nodes—a text prompt feeding into a mesh generator—connected by a single edge, organized under the "Demo" folder and flagged for bookmarks.

Type Definitions and Implementation Files

The schema is enforced across several key files in the lightningpixel/modly codebase:

• src/shared/types/electron.d.ts: Declares the Workflow, WFNode, and WFEdge interfaces used throughout the application
• src/areas/workflows/workflowRunStore.ts: Implements runtime loading, validation, and execution of workflow JSON objects
• src/shared/stores/workflowsStore.ts: Handles persistence operations including listing, saving, importing, and exporting workflows
• src/areas/workflows/preflight.ts: Performs static analysis on workflow JSON to detect missing inputs and circular dependencies
• src/areas/workflows/mockExtensions.ts: Provides mock extension definitions for testing workflow structures

Summary

• The Modly workflow JSON structure consists of a root Workflow object with metadata and two arrays: nodes and edges
• Nodes (WFNode) combine React-Flow visual properties (position, type) with runtime configuration (extensionId, enabled, params)
• Edges (WFEdge) connect node outputs to inputs using source, target, and optional handle identifiers
• Type definitions reside in src/shared/types/electron.d.ts and are validated by workflowRunStore.ts during execution
• All timestamps follow ISO-8601 format for version-control compatibility

Frequently Asked Questions

What is the minimum valid Modly workflow JSON?

A valid object requires id, name, nodes (empty array allowed), edges (empty array allowed), createdAt, and updatedAt fields conforming to the Workflow interface in src/shared/types/electron.d.ts. The description, folder, and bookmarked fields are optional.

How does Modly validate workflow JSON before execution?

The workflowRunStore.ts module loads and validates the JSON against the TypeScript interfaces, while src/areas/workflows/preflight.ts performs static analysis to check for missing inputs and circular dependencies before the runtime executes the graph.

Can I manually edit the params object in a workflow JSON file?

Yes, the params field inside WFNodeData is a free-form object that accepts any extension-specific configuration values, making it safe to edit directly for batch updates or version control operations without breaking the schema.

What determines a node's position on the canvas?

The position object with x and y number properties controls canvas placement, while optional parentId and extent: 'parent' fields constrain the node within group boundaries for nested layouts.

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