# Extension System in Modly: Key Files and Architecture Explained

> Explore Modly's extension system architecture and discover the key TypeScript files like electron.d.ts and extensionsStore.ts that power custom workflows. Understand how Modly manages extensions.

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

---

**The extension system in Modly relies on five core TypeScript modules—[`electron.d.ts`](https://github.com/lightningpixel/modly/blob/main/electron.d.ts), [`extensionsStore.ts`](https://github.com/lightningpixel/modly/blob/main/extensionsStore.ts), [`preflight.ts`](https://github.com/lightningpixel/modly/blob/main/preflight.ts), [`workflowRunStore.ts`](https://github.com/lightningpixel/modly/blob/main/workflowRunStore.ts), and [`ExtensionNode.tsx`](https://github.com/lightningpixel/modly/blob/main/ExtensionNode.tsx)—that coordinate IPC contracts, state management, workflow validation, runtime execution, and UI rendering to enable GitHub-hosted model and process extensions.**

The `lightningpixel/modly` repository implements a plugin architecture that allows developers to extend the application by dropping GitHub-hosted repositories into the app. Understanding the **extension system in Modly** requires familiarity with a specific set of TypeScript files that bridge the Electron main process, React renderer, and Python runtime. These modules handle everything from [`manifest.json`](https://github.com/lightningpixel/modly/blob/main/manifest.json) validation to process execution, creating a clean separation between declaration, state, and runtime concerns.

## IPC Contract Definitions

### src/shared/types/electron.d.ts

This file defines the TypeScript interface for the Electron IPC bridge that enables communication between the renderer (React) and main processes. It declares the methods available on `window.electron.extensions`, including `list`, `installFromGitHub`, `installFromLocal`, `uninstall`, `reload`, and `runProcess`.

When the UI needs to interact with the **extension system**, it calls these typed methods. The main process implements the underlying logic that reads the extension folder, validates the [`manifest.json`](https://github.com/lightningpixel/modly/blob/main/manifest.json) structure, and launches Python processes for model or process extensions.

## State Management Layer

### src/shared/stores/extensionsStore.ts

The central **Zustand store** that caches loaded extensions and provides actions for installing, uninstalling, and reloading them. This file tracks install progress and errors through `window.electron.extensions.onInstallProgress`.

The store maintains two critical arrays—`modelExtensions` and `processExtensions`—that populate the UI throughout the application. When you invoke `loadExtensions()`, the store calls the Electron IPC methods defined in [`electron.d.ts`](https://github.com/lightningpixel/modly/blob/main/electron.d.ts) and updates the cached state with the validated extension list.

```typescript
import { useExtensionsStore } from '@shared/stores/extensionsStore'

function InstalledExtensions() {
  const { modelExtensions, processExtensions, loadExtensions } = useExtensionsStore()
  React.useEffect(() => { loadExtensions() }, [])
  return (
    <div>
      <h3>Models</h3>
      {modelExtensions.map(e => <div key={e.id}>{e.name}</div>)}
      <h3>Processes</h3>
      {processExtensions.map(e => <div key={e.id}>{e.name}</div>)}
    </div>
  )
}

```

## Workflow Integration Components

### src/areas/workflows/preflight.ts

This module performs **static validation** of workflows before execution. It verifies that every extension node refers to a known extension and that required inputs/outputs are satisfied. The validator uses `getWorkflowExtension`, a helper that lookups extensions by ID in the store, to confirm node validity.

When validation fails, the system reports missing-extension issues that surface as UI warnings, preventing runtime errors from undefined extensions.

### src/areas/workflows/workflowRunStore.ts

The runtime execution engine that steps through workflow nodes. When encountering a node of type `extensionNode`, it invokes `window.electron.extensions.runProcess` (or model-specific endpoints) to execute the extension's Python entry point.

This file relies on the extension's [`manifest.json`](https://github.com/lightningpixel/modly/blob/main/manifest.json) to determine the command to run and maps inputs/outputs accordingly. It handles errors returned from the backend and bubbles them up to the UI with full stack traces.

```typescript
// inside workflowRunStore.ts
if (node.type === 'extensionNode') {
  const ext = getWorkflowExtension(node.data.extensionId ?? '', allExtensions)
  const result = await window.electron.extensions.runProcess(
    ext.id,
    { file: inputFilePath },
    node.data.params
  )
  if (!result.success) throw new Error(result.error ?? 'Process extension failed')
  // result.result contains the processed file path
}

```

### src/areas/workflows/nodes/ExtensionNode.tsx

The React component that renders extension nodes inside the visual workflow editor. It displays the extension name, configurable parameters, and connection pins (input/output sockets) based on the extension's declared schema.

This component pulls the extension list from `useExtensionsStore` and resolves output types to color-code connection handles in the node graph.

## Built-in Process Extensions

Modly ships with several **built-in process extensions** located in `src/areas/workflows/nodes/*/processor.*`. These follow the same runtime contract as external extensions but reside in the `builtin-extensions` folder.

Key examples include:

- **Mesh Optimizer** ([`src/areas/workflows/nodes/mesh-optimizer/processor.ts`](https://github.com/lightningpixel/modly/blob/main/src/areas/workflows/nodes/mesh-optimizer/processor.ts)) – Optimizes GLTF meshes
- **Mesh Exporter** ([`src/areas/workflows/nodes/mesh-exporter/processor.ts`](https://github.com/lightningpixel/modly/blob/main/src/areas/workflows/nodes/mesh-exporter/processor.ts)) – Exports to GLTF format
- **Mesh Smoother** ([`src/areas/workflows/nodes/mesh-smoother/processor.py`](https://github.com/lightningpixel/modly/blob/main/src/areas/workflows/nodes/mesh-smoother/processor.py)) – Python-based smoothing algorithms
- **Mesh Repair** ([`src/areas/workflows/nodes/mesh-repair/processor.py`](https://github.com/lightningpixel/modly/blob/main/src/areas/workflows/nodes/mesh-repair/processor.py)) – Automated mesh repair routines
- **Mesh Remesher** – Additional geometry processing utilities

Each processor reads incoming files, executes Python routines, and returns processed assets that downstream nodes consume.

## Extension Lifecycle in Modly

The **extension system** follows a five-stage lifecycle:

1. **Discovery** – On startup, `extensionsStore.loadExtensions()` invokes `window.electron.extensions.list()`. The main process scans `extensionsDir`, validates each [`manifest.json`](https://github.com/lightningpixel/modly/blob/main/manifest.json), and returns typed arrays of `ModelExtension` or `ProcessExtension` objects.

2. **Installation** – Calling `extensionsStore.installFromGitHub(url)` triggers the Electron bridge to clone the repository, run install scripts, and stream progress events (`downloading`, `extracting`, `validating`, `setting_up`).

3. **Workflow Integration** – Dragging an **Extension Node** into the visual editor creates a node with `data.extensionId` set to the extension identifier (e.g., `pack/process-node`).

4. **Execution** – `workflowRunStore` iterates through nodes; for `extensionNode` types, it calls `window.electron.extensions.runProcess(extensionId, input, params)`, launching the Python entry point defined in the manifest.

5. **Result Propagation** – Processed assets feed back into the workflow graph, allowing downstream nodes like **Mesh Exporter** to consume the output.

```typescript
await useExtensionsStore.getState().installFromGitHub(
  'https://github.com/lightningpixel/modly-hunyuan3d-mini-extension'
)

```

## Summary

- **[`src/shared/types/electron.d.ts`](https://github.com/lightningpixel/modly/blob/main/src/shared/types/electron.d.ts)** defines the IPC contract between React and Electron main process for all extension operations.
- **[`src/shared/stores/extensionsStore.ts`](https://github.com/lightningpixel/modly/blob/main/src/shared/stores/extensionsStore.ts)** manages extension state, installation progress, and provides the `useExtensionsStore` hook.
- **[`src/areas/workflows/preflight.ts`](https://github.com/lightningpixel/modly/blob/main/src/areas/workflows/preflight.ts)** validates workflows before execution to ensure all referenced extensions exist and have correct signatures.
- **[`src/areas/workflows/workflowRunStore.ts`](https://github.com/lightningpixel/modly/blob/main/src/areas/workflows/workflowRunStore.ts)** executes workflow nodes by invoking extension processes through the Electron bridge.
- **[`src/areas/workflows/nodes/ExtensionNode.tsx`](https://github.com/lightningpixel/modly/blob/main/src/areas/workflows/nodes/ExtensionNode.tsx)** renders extension nodes in the visual editor with proper input/output handles.
- **Built-in extensions** in `src/areas/workflows/nodes/*/` demonstrate the same contract as external extensions, providing reference implementations for mesh processing.

## Frequently Asked Questions

### How does Modly validate extension manifests before execution?

The [`src/areas/workflows/preflight.ts`](https://github.com/lightningpixel/modly/blob/main/src/areas/workflows/preflight.ts) module performs static analysis on workflow graphs before runtime. It uses `getWorkflowExtension` to verify that every `extensionNode` references a valid extension ID and that the node's inputs and outputs match the types declared in the extension's [`manifest.json`](https://github.com/lightningpixel/modly/blob/main/manifest.json). Failed validations surface as UI warnings rather than runtime crashes.

### What is the difference between model and process extensions in the Modly extension system?

**Model extensions** typically load AI models or specialized processing capabilities that run inference tasks, while **process extensions** handle data transformations like mesh optimization or file format conversion. Both follow the same IPC contract defined in [`electron.d.ts`](https://github.com/lightningpixel/modly/blob/main/electron.d.ts), but they populate separate arrays in [`extensionsStore.ts`](https://github.com/lightningpixel/modly/blob/main/extensionsStore.ts) (`modelExtensions` vs `processExtensions`) to categorize their capabilities in the UI.

### How do I install a third-party extension from GitHub in Modly?

Use the `installFromGitHub` method from the extensions store: `await useExtensionsStore.getState().installFromGitHub('https://github.com/user/repo')`. The main process clones the repository, validates the [`manifest.json`](https://github.com/lightningpixel/modly/blob/main/manifest.json), runs any defined install scripts, and streams progress events back to the UI through the `onInstallProgress` listener.

### Where are built-in extensions located compared to external ones?

Built-in extensions reside in the `src/areas/workflows/nodes/` directory within the application source (e.g., [`mesh-optimizer/processor.ts`](https://github.com/lightningpixel/modly/blob/main/mesh-optimizer/processor.ts)), while external extensions are cloned into the configured `extensionsDir` folder at runtime. Both types implement the same interface, but built-in extensions ship with the application and do not require separate installation through the GitHub workflow.