Basic Concepts

PtahJs is a layered low-code engine. Understanding how the core packages fit together makes the runtime and designer APIs much easier to use.

Architecture Overview

@ptahjs/ui-vue
  Vue integration layer
  components, renderers, bootstrap utilities

@ptahjs/designer
  design-time layer
  commands, history, DnD, editing

@ptahjs/runtime
  runtime layer
  schema compilation, queries, lifecycle chain, hotkeys

@ptahjs/kernel
  core state layer
  IRGraph, change tracking, subscriptions, resources

---

Kernel

@ptahjs/kernel is the lowest-level package. It owns the core state of the DSL tree, also called the IRGraph.

Key responsibilities:

• Maintain the IRGraph
• Track state changes with versions
• Notify subscribers asynchronously
• Support batch updates
• Manage the shared resource system

In most cases you use Runtime, not Kernel, directly.

---

IRGraph

The IRGraph is the compiled page structure stored as indexed sections for fast lookup.

Section	Description
scenesById	All scenes by ID
modulesById	All modules by ID
childrenIdsByParentId	Parent-child relationships
eventsById	All events by ID
eventIdsByOwnerId	Event IDs grouped by owner
sceneIdOrder	Ordered scene IDs
subSchemasById	Sub-schema map

When you call runtime.schema(data), the incoming page JSON is compiled into this structure.

---

Runtime

@ptahjs/runtime extends Kernel with business-facing APIs.

• schema(data) compiles page schema into the IRGraph
• Query helpers such as getSceneIds(), getSceneById(id), getModuleById(id)
• Current selection APIs such as setCurrentSceneId() and setCurrentModuleId()
• lifecycleChain for hook-based processing
• hotkeys for keyboard shortcuts

runtime.schema(pageJson);

const sceneIds = runtime.getSceneIds();
const module = runtime.getModuleById('module-123');
const events = runtime.getOwnerEvents('scene-456');

---

Designer

@ptahjs/designer adds design-time editing on top of Runtime.

• Command-based edits
• Undo/redo history
• Built-in drag and drop
• Clipboard operations for modules
• Export through designer.getPageSchema()

const moduleId = designer.addModule({
    type: 'UiButton',
    parentId: 'scene-1',
    index: 0,
});

designer.updateModule({
    id: moduleId,
    patch: { props: { label: 'Click me' } },
});

designer.undo();

---

LifecycleChain

runtime.lifecycleChain is a synchronous processing pipeline.

• Use addStep(type, fn) to register hooks
• Hooks run in registration order
• Returning undefined keeps the previous value

import { LIFECYCLE_TYPE } from '@ptahjs/kernel';

runtime.lifecycleChain.addStep(LIFECYCLE_TYPE.BEFORE_TRANSFORM_DATA, (schema) => {
    return schema;
});

runtime.lifecycleChain.addStep(LIFECYCLE_TYPE.GET_PAGE_SCHEMA_DATA, (schema) => {
    return schema;
});

---

Resource System

The resource system stores shared configuration such as renderers, module schema maps, and parameter components.

import { RESOURCE_TYPE } from '@ptahjs/kernel';

const config = runtime.getResource(RESOURCE_TYPE.RENDERER_CONFIG);

---

Scene and Module

A scene is a top-level page unit. A module is a component instance placed inside a scene or another module.

Typical page structure:

Page Schema
- Scene 1
  - UiHeader
  - UiGrid
    - Slot: default
      - UiButton
- Scene 2
- Modal 1

---

Event Flows

In PtahJs, an event is a flow definition rather than a DOM event object. Events belong to a scene or module and are executed by the flow runner.

---

ui-vue

@ptahjs/ui-vue is the Vue integration layer.

• Bootstrap utilities: useRuntimeApp(), useDesignerApp()
• Vue plugin: createPtah()
• Built-in components: Preview, DesignerRoot, ScenesWidget, ModulesWidget, WorkspaceWidget, ParameterWidget, EventsWidget

See the API Reference for details.