What Store Types Are Available in the OpenMAIC Persistence Layer?

The OpenMAIC persistence layer exposes three primary store types—InMemoryStore, IndexedDBStore, and ServerStore—along with specialized variants for binary assets and key-value data, all implementing a unified Store interface.

The THU-MAIC/OpenMAIC repository provides a modular persistence layer that abstracts storage operations behind a common interface. This architecture allows developers to swap between in-memory caching, browser-based IndexedDB, and remote server storage without changing application logic. Understanding the available store types is essential for configuring the optimal data persistence strategy across development, testing, and production environments.

Primary Store Types in OpenMAIC

The persistence layer defines three core implementations in lib/persistence/, each targeting a specific runtime environment or durability requirement.

InMemoryStore (Non-Durable Fallback)

The InMemoryStore serves as the default fallback when no durable storage is available, such as during server-side rendering or unit testing. Located in lib/persistence/in-memory-store.ts, this implementation stores data in plain JavaScript objects that persist only for the duration of the process.

IndexedDBStore (Client-Side Browser Storage)

For browser environments, the IndexedDBStore provides durable client-side persistence using the Dexie wrapper around IndexedDB. Defined in lib/persistence/indexeddb-store.ts, this store handles scenes, assets, and metadata locally within the browser's storage quota.

ServerStore (Remote API Persistence)

The ServerStore enables centralized, remote persistence by communicating with backend endpoints under api/persistence/*. Implemented in lib/persistence/server-provider.ts, this store supports custom server configurations including S3-compatible backends or traditional databases.

Specialized Store Types

Beyond the primary storage interface, OpenMAIC provides specialized stores for specific data shapes and access patterns.

AssetByteStore (Binary Asset Handling)

The AssetByteStore manages raw binary payloads such as images, audio, and video files. Located in lib/persistence/asset-byte-store.ts, this store isolates large binary objects from JSON document storage to optimize retrieval performance and memory usage.

KVStore (Key-Value Persistence)

For configuration flags and short-lived caches, the KVStore offers lightweight key-value operations. Defined in lib/persistence/kv-persist.ts, this implementation supports simple string-based storage without the overhead of full document serialization.

Runtime Store Selection

The persistence layer uses a factory pattern to instantiate the appropriate store type based on environment configuration.

The createPersistenceStore function in lib/persistence/store-factory.ts selects implementations dynamically:

import { createPersistenceStore } from '@/lib/persistence/store-factory';

const persistence = createPersistenceStore({
  type: process.env.NEXT_PUBLIC_PERSISTENCE === '1' ? 'server' :
        typeof window !== 'undefined' ? 'indexeddb' : 'memory',
});

Working with Store Implementations

All store implementations conform to the same interface, enabling consistent CRUD operations regardless of the underlying storage mechanism.

Saving documents to any active store:

await persistence.saveDocument({
  id: 'stage-42',
  content: JSON.stringify(sceneData),
});

Storing binary assets via the specialized byte store:

import { getAssetByteStore } from '@/lib/persistence/asset-byte-store';

await getAssetByteStore().put('image-123', blob);

Managing configuration flags with the key-value store:

import { kvPersist } from '@/lib/persistence/kv-persist';

await kvPersist.set('hasSeenTutorial', true);
const seen = await kvPersist.get('hasSeenTutorial');

Summary

• The OpenMAIC persistence layer provides InMemoryStore, IndexedDBStore, and ServerStore as primary implementations.
• InMemoryStore in lib/persistence/in-memory-store.ts serves non-durable fallback scenarios such as SSR and testing.
• IndexedDBStore in lib/persistence/indexeddb-store.ts handles browser-based client storage via the Dexie wrapper.
• ServerStore in lib/persistence/server-provider.ts routes data to remote APIs supporting S3 or custom backends.
• Specialized stores include AssetByteStore for binary data in lib/persistence/asset-byte-store.ts and KVStore for key-value pairs in lib/persistence/kv-persist.ts.
• The factory pattern in lib/persistence/store-factory.ts enables runtime selection based on environment variables like NEXT_PUBLIC_PERSISTENCE.

Frequently Asked Questions

What is the default store type when running OpenMAIC in a browser?

When typeof window is defined and NEXT_PUBLIC_PERSISTENCE is not set to server mode, the factory automatically instantiates IndexedDBStore to provide durable client-side storage.

How does OpenMAIC handle binary assets differently from JSON documents?

Binary assets utilize the AssetByteStore defined in lib/persistence/asset-byte-store.ts, which operates separately from document stores to optimize memory usage and supports direct Blob operations rather than JSON serialization.

Can I configure OpenMAIC to use a custom S3-compatible storage backend?

Yes. The ServerStore implementation in lib/persistence/server-provider.ts communicates via HTTP to api/persistence/* endpoints, allowing the backend to route requests to S3, MinIO, or any custom storage provider without modifying client-side code.

Is the InMemoryStore suitable for production workloads?

No. The InMemoryStore is designed exclusively for testing and server-side rendering fallback scenarios, as data persists only for the duration of the JavaScript process and is lost on page reload.

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