Modly Workflow Definitions: Examples and JSON Structure Explained

Modly stores every workflow as a plain JSON document that conforms to the Workflow TypeScript interface declared in src/shared/types/electron.d.ts, allowing you to define, import, and version-control complex node graphs declaratively.

Modly is an open-source visual workflow engine for 3D content generation. Understanding how workflow definitions are structured lets you author complex pipelines programmatically, share reusable templates with your team, or debug execution issues by inspecting the underlying JSON.

Workflow JSON Schema and Required Fields

According to the Modly source code, the Workflow type in src/shared/types/electron.d.ts (lines 31-43) dictates the exact shape of every workflow file. A valid workflow JSON must contain these top-level fields:

• id – A unique identifier (typically UUID format) for the workflow instance.
• name – The human-readable title displayed in the Modly UI browser.
• description – Optional longer text explaining the workflow’s purpose.
• folder (optional) – Grouping name shown in the workflow browser; omitting places the workflow at root level.
• bookmarked (optional) – Boolean flag that pins the workflow in the Bookmarks section.
• nodes – Array of WFNode objects representing each processing step.
• edges – Array of WFEdge objects defining connections between node outputs and inputs.
• createdAt / updatedAt – ISO 8601 timestamps used for sorting and version tracking.

Node definitions are not hardcoded. Instead, Modly discovers available nodes by scanning extension manifests. Each extension ships a manifest.json that registers its capabilities with the workflow engine.

Node Definitions from Extension Manifests

Extensions—whether model extensions or process extensions—declare their nodes via JSON manifests. For example, the Mesh Exporter process extension defines its Export Mesh node in src/areas/workflows/nodes/mesh-exporter/manifest.json (lines 11-36).

The manifest specifies:

• Input/output port schemas determining which node types can connect.
• Parameter schemas defining configurable options (e.g., export_format enum, output_path string).
• Extension ID used to reference the node in workflow files (e.g., "extensionId": "mesh-exporter").

When you build a workflow in the UI, Modly validates connections against these schemas to prevent type mismatches between nodes.

Creating and Saving Workflows

The typical lifecycle for workflow creation involves four stages:

1. Add nodes – Select nodes from the Generate tab (e.g., Image → Generate Mesh → Export Mesh).
2. Connect ports – Drag connections between output and input ports; the UI auto-generates corresponding edges array entries.
3. Serialize – The UI saves the graph as JSON to your workflows directory, defaulting to ~/Modly/workspace/workflows.
4. Import/Load – Use window.electron.workflows.import() programmatically, or open files directly via the workflow browser.

The src/shared/stores/workflowsStore.ts module handles persistence, converting the in-memory React Flow graph into the JSON structure defined in the typings.

Complete Modly Workflow JSON Example

Below is a fully functional workflow definition that takes an input image, generates a 3D mesh using the Hunyuan3D mini model, and exports the result as a GLB file:

{
  "id": "example-01",
  "name": "Image → Mesh → GLB",
  "description": "Simple demo workflow turning a photo into a GLB mesh.",
  "folder": "Demo",
  "bookmarked": true,
  "nodes": [
    {
      "id": "img",
      "type": "image-input",
      "position": { "x": 0, "y": 0 },
      "data": {
        "extensionId": "modly-image-input",
        "inputType": "image",
        "enabled": true,
        "params": {}
      }
    },
    {
      "id": "gen",
      "type": "model",
      "position": { "x": 250, "y": 0 },
      "data": {
        "extensionId": "modly-hunyuan3d-mini-extension",
        "inputType": "image",
        "enabled": true,
        "params": { "strength": 0.8 }
      }
    },
    {
      "id": "export",
      "type": "process",
      "position": { "x": 500, "y": 0 },
      "data": {
        "extensionId": "mesh-exporter",
        "inputType": "mesh",
        "enabled": true,
        "params": {
          "export_format": "glb",
          "output_path": ""
        }
      }
    }
  ],
  "edges": [
    { "id": "e1", "source": "img", "target": "gen" },
    { "id": "e2", "source": "gen", "target": "export" }
  ],
  "createdAt": "2026-08-19T00:00:00.000Z",
  "updatedAt": "2026-08-19T00:00:00.000Z"
}

Key implementation details:

• Node wiring: The edges array creates a directed graph where the image node feeds the model node, and the model node feeds the exporter.
• Extension references: Each node’s data.extensionId must match an ID registered in its respective manifest.json.
• Parameter validation: The exporter’s params object matches the schema defined in src/areas/workflows/nodes/mesh-exporter/manifest.json (lines 17-34), accepting glb, obj, or stl for export_format.

Critical Source Files for Workflow Definitions

File	Purpose
src/shared/types/electron.d.ts	Declares the Workflow, WFNode, and WFEdge TypeScript interfaces used throughout the application.
src/areas/workflows/nodes/**/manifest.json	Extension-specific node definitions (e.g., Mesh Exporter manifest declaring export parameters).
src/shared/stores/workflowsStore.ts	Manages CRUD operations for workflow JSON files via the Electron IPC bridge.
src/areas/workflows/workflowRunStore.ts	Executes workflows by traversing nodes/edges and invoking the correct extension handlers.

These files enforce that every workflow definition remains valid JSON while supporting extensible node types through the manifest system.

Summary

• Modly workflows are valid JSON files conforming to the Workflow interface in src/shared/types/electron.d.ts.
• Each workflow contains nodes (processing steps) and edges (data flow connections) arrays.
• Nodes are provided by extensions that declare their schemas in local manifest.json files.
• Workflows are stored by default in ~/Modly/workspace/workflows and can be imported via window.electron.workflows.import().
• You can hand-author workflow definitions to version-control pipelines or generate them dynamically from external tools.

Frequently Asked Questions

What file format does Modly use for workflow definitions?

Modly uses plain JSON files with a specific schema defined by the Workflow type in src/shared/types/electron.d.ts. This format is portable, human-readable, and compatible with version control systems like Git.

Where are workflow files stored on disk?

By default, Modly saves workflow JSON files to ~/Modly/workspace/workflows (inside the user's home directory). You can open, edit, or backup these files directly, and the changes will reflect in the Modly UI upon refresh.

How does Modly know which nodes are available in a workflow?

Modly discovers nodes by reading manifest.json files inside each extension directory under src/areas/workflows/nodes/. Each manifest registers an extensionId and defines the node's parameters, which the workflow engine uses to validate JSON workflows and populate the UI node palette.

Can I create Modly workflows without using the visual editor?

Yes. Because workflows are standard JSON documents, you can write them manually in any text editor or generate them programmatically. Ensure your JSON validates against the Workflow type structure and that all extensionId values match installed extensions. Import the file using window.electron.workflows.import() or place it in the workflows directory to load it automatically.

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