Skip to main content

5-Minute Quickstart Guide

This guide walks you through compiling your first JSON business rule, executing it against contextual input data, and launching the live terminal dashboard.

1. Prerequisites​

  • Java Development Kit (JDK): Version 17 or higher (temurin-17, openjdk-17, or graalvm-17).
  • Operating System: Linux, macOS, or Windows (WSL2).

Verify your environment:

java -version

2. Compile a Business Rule​

Helix rules are authored as standard JSON objects containing a name, version, boolean expression, and typed input schema:

examples/rules/fraud-detection.json
{
    "name": "FraudDetectionRule",
    "version": "1.0.0",
    "expression": "amount > 10000 && country != \"US\"",
    "inputSchema": {
        "amount": "int",
        "country": "String"
    }
}

Compile the rule into raw JVM bytecode:

./scripts/start-helix.sh compile --rule examples/rules/fraud-detection.json --output json

Result:

{
  "status" : "SUCCESS",
  "ruleName" : "FraudDetectionRule",
  "ruleVersion" : "1.0.0",
  "compilationTimeMs" : "177.396"
}

3. Execute Rule with Context Data​

Now provide contextual runtime parameters to evaluate the rule:

examples/rules/sample-context.json
{
  "amount": 15000,
  "country": "UK"
}

Execute synchronously, asynchronously, via batch, or using Java 21 Loom virtual threads:

./scripts/start-helix.sh execute \
  --rule examples/rules/fraud-detection.json \
  --context examples/rules/sample-context.json \
  --mode virtual \
  --output json

Output:

{
  "status" : "SUCCESS",
  "ruleName" : "FraudDetectionRule",
  "executionMode" : "VIRTUAL",
  "resultValue" : true,
  "durationMs" : "0.412"
}

4. Launch the Interactive REPL & Disassembler​

Helix includes a fully-featured JLine 3 terminal REPL for ad-hoc rule authoring, live AST inspection, and raw bytecode disassembly:

./scripts/start-helix.sh repl

Inside the shell, evaluate expressions and inspect generated bytecode opcodes immediately:

helix> :load examples/rules/fraud-detection.json
Loaded rule 'FraudDetectionRule' (v1.0.0)

helix> :eval {"amount": 15000, "country": "UK"}
Result: true (took 12.4 us)

helix> :disasm
// Disassembled Bytecode for FraudDetectionRule:
public boolean eval(com.helix.api.ExecutionContext);
  Code:
     0: aload_1
     1: ldc           #14 // String amount
     3: invokevirtual #20 // Method ExecutionContext.getInt:(Ljava/lang/String;)I
     6: ldc           #21 // int 10000
     8: if_icmple     24
    11: ldc           #23 // String US
    13: aload_1
    14: ldc           #25 // String country
    16: invokevirtual #28 // Method ExecutionContext.getString:(Ljava/lang/String;)Ljava/lang/String;
    19: invokevirtual #34 // Method String.equals:(Ljava/lang/Object;)Z
    22: ifne          28
    25: iconst_1
    26: ireturn
    27: iconst_0
    28: ireturn

5. Profile & Generate In-Terminal Flame Graphs​

Helix features an in-memory folded stack trace aggregator with real-time ASCII flame graph rendering and SVG export:

# Capture 10 seconds of CPU profiling and render an ASCII flame graph to terminal
./scripts/start-helix.sh profile --flamegraph --seconds 10

To export an interactive vector SVG or HTML flame graph:

./scripts/start-helix.sh profile --flamegraph --seconds 10 --export target/flamegraphs/helix-flamegraph.svg

6. Launch Interactive Terminal UI (TUI) Dashboard​

To inspect real-time CPU utilization, Metaspace growth, GC pause rates, L1/L2/L3 cache metrics, and interactive flame graph navigation in your terminal:

./scripts/start-helix.sh profile --tui
Interactive Controls & Flame Graph View
  • Press F to switch to the Full-Screen Unicode ASCII Flame Graph view.
  • Use Arrow keys to navigate stack frames.
  • Press Enter to zoom into any stack frame; press Backspace to zoom out.
  • Press / to filter frames by keyword.
  • Press E to export the current flame graph view as vector SVG.
  • Press F1 to trigger forced GC sweeps or F2 to invalidate cache tiers.