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

> Discover how Modly persists data using a file-system architecture. Learn how JSON sidecars replace traditional databases, making files the single source of truth.

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

---

**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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/src/shared/types/assetLibrary.ts). Runtime stores such as [`src/areas/workflows/workflowRunStore.ts`](https://github.com/lightningpixel/modly/blob/main/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:

```typescript
// 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.

```typescript
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`](https://github.com/lightningpixel/modly/blob/main/.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`](https://github.com/lightningpixel/modly/blob/main/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:

```typescript
// 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`](https://github.com/lightningpixel/modly/blob/main/electron/main/artifact-registry-service.ts) generate catalogs by walking the file tree and parsing entries.
- **Side-car metadata**: JSON files (like [`.rigmeta.json`](https://github.com/lightningpixel/modly/blob/main/.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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/.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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/electron/main/artifact-registry-service.ts), providing accurate chronological data without database overhead.