How Data Is Persisted in the Modly Backend: File-System Architecture Explained

Modly persists all data on the local file-system inside the workspace directory, treating files as the single source of truth and using JSON side-cars for metadata rather than a traditional database.

The Modly backend (lightningpixel/modly) deliberately avoids traditional database infrastructure. Instead, it implements a lightweight persistence strategy where the user's workspace directory serves as the primary data store, supplemented by electron-store for user preferences.

Workspace Asset Persistence

Modly treats two specific folders within the workspace—Workflows and Exports—as persistent asset containers. The backend scans these directories recursively, skipping hidden or temporary folders, and treats every discovered file as a catalog entry that represents a persistent asset.

The Asset Discovery Process

In electron/main/artifact-registry-service.ts, the collectFiles function walks the directory tree to build a comprehensive asset catalog. This function works in conjunction with buildEntry to transform raw file paths into structured entries according to the type definitions in src/shared/types/assetLibrary.ts. Runtime stores such as src/areas/workflows/workflowRunStore.ts reference these persisted assets during workflow execution.

The following IPC call demonstrates how the renderer requests the asset library from this file-system scan:

// Renderer side – request the list
const result = await ipcRenderer.invoke('workspace:library:list');

// Backend side – walks the workspace and builds entries
// (see collectFiles → buildEntry in artifact-registry-service.ts)

Reading Individual Assets

When retrieving specific assets, Modly validates associated metadata by checking for JSON side-car files. The backend uses readFile to load these configurations and extracts fields such as sourceWorkspacePath and manifestWorkspacePath to verify asset relationships.

const { workspacePath } = { workspacePath: 'Workflows/example.glb' };
const entry = await ipcRenderer.invoke('workspace:library:read', { workspacePath });
/*
{
  success: true,
  entry: { id, workspacePath, capability: 'mesh', … },
  preview: { kind: '3d-model', viewerKind: 'glb' }
}
*/

Metadata and Side-Car Files

Assets requiring additional metadata—such as GLB meshes with corresponding .rigmeta.json files—store this information alongside the asset rather than in a separate database. The backend parses these JSON side-cars to enrich the asset entries with validation data and relationship mappings, maintaining all auxiliary data within the workspace folder structure.

User Settings Persistence

Configuration data follows a different persistence path than workspace assets. In electron/main/settings-store.ts, Modly utilizes electron-store to persist user preferences, writing JSON files to platform-specific directories such as %APPDATA%/Modly/settings.json on Windows.

Electron-Store Implementation

The settings store provides type-safe getters and setters that abstract the underlying file operations:

// In electron/main/settings-store.ts
import Store from 'electron-store';
const store = new Store();

export const getTheme = () => store.get('theme', 'light');
export const setTheme = (value: string) => store.set('theme', value);

This approach ensures that UI preferences, recent projects, and other configuration survive application restarts without requiring database connectivity.

Timestamp Tracking Without a Database

Modly eliminates the need for database timestamp columns by extracting creation and modification dates directly from the file-system. The backend uses Node.js stat calls to retrieve birthtime (creation time) and mtime (modification time) from each file, attaching these values directly to asset entries for reliable history tracking without external dependencies.

Summary

• File-system first: Modly uses the workspace directory (Workflows and Exports folders) as the primary data store, eliminating traditional database dependencies.
• Asset scanning: The collectFiles and buildEntry functions in electron/main/artifact-registry-service.ts generate catalogs by walking the file tree and parsing entries.
• Side-car metadata: JSON files (like .rigmeta.json) store auxiliary asset data adjacent to the files they describe, using sourceWorkspacePath and manifestWorkspacePath for validation.
• User settings: Runtime configuration persists via electron-store in electron/main/settings-store.ts, writing to platform-specific JSON files.
• Native timestamps: File creation and modification times come directly from stat system calls (birthtime and mtime), not database records.

Frequently Asked Questions

Does Modly use a database for persistence?

No. According to the lightningpixel/modly source code, the backend does not use a traditional database. All persistent data resides on the local file-system, with workspace folders serving as the single source of truth for assets and electron-store handling user preferences.

How does Modly handle asset metadata?

Modly stores asset metadata in JSON side-car files (such as .rigmeta.json) that sit alongside the primary asset files. When the backend loads an asset via workspace:library:read, it validates these side-cars using fields like sourceWorkspacePath and manifestWorkspacePath to ensure data integrity.

Where are user settings stored in Modly?

User settings persist via electron-store, which writes to a JSON file in the platform-specific user-data directory. On Windows, this location is typically %APPDATA%/Modly/settings.json, as implemented in electron/main/settings-store.ts. This file-based approach aligns with Modly's overall architecture of avoiding external database dependencies.

How does Modly track when assets were created or modified?

Instead of database timestamps, Modly extracts birthtime (creation time) and mtime (modification time) directly from the file-system using Node.js stat calls. These values attach to asset entries during the catalog build process in electron/main/artifact-registry-service.ts, providing accurate chronological data without database overhead.

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