Quickstart: Visual Graphs to Domain Code

Each node is a { id, type, data } triple. Edges connect nodes via named sourceHandle / targetHandle ports. There is no separate "register" step — the generator decides what node types it understands.

```typescript import type { ASTEdge, ASTNode } from "@aeion/core/compiler";

// A small NanoEngine graph: load a model, attach a pointer event, apply an impulse const nodes: ASTNode[] = [ { id: "model", type: "nanoModel", data: { url: "soda_can.glb", isDynamic: true }, }, { id: "event", type: "nanoPointerEvent", data: { eventType: "onPointerDown" }, }, { id: "impulse", type: "nanoApplyImpulse", data: { x: 0, y: 8, z: -2 } }, ];

const edges: ASTEdge[] = [ { id: "e1", source: "model", target: "event", sourceHandle: "out", targetHandle: "target", }, { id: "e2", source: "event", target: "impulse", sourceHandle: "out", targetHandle: "trigger", }, { id: "e3", source: "model", target: "impulse", sourceHandle: "out", targetHandle: "target", }, ]; ```

Type system signals live in the node's data — there is no schema validator forced by the engine. You can lay one on (Zod, custom React UI, etc.) at the editor layer if you want type-checked ports.

Persistence — graphs are plain JSON: { nodes, edges }. Save to any storage. Git-diffable, portable across tenants.

The engine doesn't ship a proprietary editor — it composes with the open-source @xyflow/react (formerly ReactFlow). Bring your own node components.

```tsx import { useState, useCallback } from "react"; import { ReactFlow, ReactFlowProvider, Controls, Background, addEdge, applyNodeChanges, applyEdgeChanges, type Node, type Edge, type Connection, } from "@xyflow/react"; import "@xyflow/react/dist/style.css"; import { NanoModelNode, NanoPointerEventNode, NanoApplyImpulseNode, } from "./MyNodes"; // your own node renderers

const nodeTypes = { nanoModel: NanoModelNode, nanoPointerEvent: NanoPointerEventNode, nanoApplyImpulse: NanoApplyImpulseNode, };

export function MyGraphEditor() { const [nodes, setNodes] = useState<Node[]>(/ initial nodes /); const [edges, setEdges] = useState<Edge[]>(/ initial edges /);

return ( <ReactFlowProvider> <ReactFlow nodes={nodes} edges={edges} nodeTypes={nodeTypes} onNodesChange={useCallback( (changes) => setNodes((nds) => applyNodeChanges(changes, nds)), [], )} onEdgesChange={useCallback( (changes) => setEdges((eds) => applyEdgeChanges(changes, eds)), [], )} onConnect={useCallback( (params: Connection) => setEdges((eds) => addEdge(params, eds)), [], )} fitView > <Background /> <Controls /> </ReactFlow> </ReactFlowProvider> ); } ```

The Spatial module's own scene editor is built exactly this way — use it as a reference for the shape of a production-grade domain editor.

Editor concerns the engine intentionally leaves to you:

• Node palette UI / drag-and-drop catalog
• Port-type validation feedback
• Live code preview pane (call compiler.compile() on each change)
• Auto-layout, minimap, multi-select, group / collapse

The library handles graph state + rendering; the engine handles compilation. The two are decoupled by design.

The ASTCompiler constructor takes a generator; .compile() takes nodes, edges, and the output-node type (string or array).

```typescript import { ASTCompiler, NanoEngineGenerator } from "@aeion/core/compiler";

const compiler = new ASTCompiler(new NanoEngineGenerator()); const result = compiler.compile(nodes, edges, "nanoApplyImpulse");

if (result.errors.length > 0) { console.error("Compile failed:", result.errors); } else { console.log(result.code); // result.metadata — generator-specific structured output (optional) } ```

Execution model:

1. The compiler finds every node matching the output type.
2. From each output, it walks backward via edges, depth-first.
3. Each node passes its incoming edges to the generator's generateNode, which returns { code, varName }.
4. The compiler concatenates the chunks and hands them to finalize for wrapping.
5. Errors are caught per-node — one bad node returns code: "ERROR_VAR" and a recorded error rather than aborting.

Zero-runtime philosophy — the engine compiles to native source for the target environment (TSX, Python, Solidity, G-Code, etc.). There is no interpreter in the output; the generated code runs as fast as hand-written code on the same target.

The engine ships no built-in test runner — graphs are compiled into ordinary source, so test the source with whatever test framework that target uses (Vitest / Jest for TypeScript outputs, pytest for Python, Foundry for Solidity, etc.).

Recommended scenario pattern for visual logic:

```typescript import { describe, it, expect } from "vitest"; import { ASTCompiler, TypeScriptETLGenerator } from "@aeion/core/compiler";

const compiler = new ASTCompiler(new TypeScriptETLGenerator());

describe("My pricing graph", () => { it("compiles cleanly", () => { const { code, errors } = compiler.compile( pricingGraph.nodes, pricingGraph.edges, "output", ); expect(errors).toEqual([]); expect(code).toContain("function compiled"); });

it("produces the expected price for a wholesale order", async () => { const { code } = compiler.compile( pricingGraph.nodes, pricingGraph.edges, "output", ); const fn = new Function("input", ${code}\nreturn compiled(input);); expect(fn({ qty: 50, segment: "wholesale", basePrice: 10 })).toEqual({ finalPrice: 280, }); }); }); ```

Anti-patterns to avoid:

• Don't unit-test the generator's generateNode in isolation if the per-node output is glue — test the compiled program end-to-end instead.
• Don't snapshot-test the raw code string for high-volatility graphs; semantics change less often than source layout.
• Don't compile inside hot UI loops without debouncing — the compiler is fast (~1-10ms for typical graphs), but graph edits fire on every keystroke, so debounce anyway.

Once the graph compiles cleanly and the generated code passes your scenarios, deploy to your target environment.

Server-side execution:

• Persist the graph JSON in a collection (e.g., pricing_graphs, workflow_graphs).
• On a relevant event, fetch the graph, compile, and execute the result in a sandbox (WasmGenerator output runs in a WASM runtime; TypeScriptETLGenerator output runs in a BullMQ worker after type-check).

Edge / device execution:

• Compile once on save, store the artifact alongside the graph.
• ReactNativeGenerator ships the SDUI JSON; MicroPythonGenerator ships the .py payload to ESP32 devices via OTA flash.
• MavlinkGenerator outputs are uploaded to drones via a QGroundControl-compatible flight plan.

Visual-first source of truth:

• The graph is authoritative; the compiled code is a derived artifact. Re-compile on every save so the running system always matches what users see in the editor.
• Diffing graphs in PRs gives reviewers a domain-level change set ("added a 10% wholesale tier") instead of a code diff that re-emits all nodes.

Cross-vertical reuse:

• The same compiler engine drives Pricing CPQ, Blueprint workflows, Mobile Builder SDUI, Spatial NanoEngine scenes, Singularity ETL transformers, Construction BIM exports, and Smart Spaces firmware. One mental model, thirty-plus targets.