# Modly Workflow Definitions: Examples and JSON Structure Explained

> Explore Modly workflow definitions with clear examples and understand the JSON structure. Learn how to define, import, and version-control node graphs declaratively.

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

---

**Modly stores every workflow as a plain JSON document that conforms to the `Workflow` TypeScript interface declared in [`src/shared/types/electron.d.ts`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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:

```json
{
  "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`](https://github.com/lightningpixel/modly/blob/main/manifest.json)**.
- **Parameter validation**: The exporter’s `params` object matches the schema defined in **[`src/areas/workflows/nodes/mesh-exporter/manifest.json`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/src/shared/stores/workflowsStore.ts) | Manages CRUD operations for workflow JSON files via the Electron IPC bridge. |
| [`src/areas/workflows/workflowRunStore.ts`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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.