DTRules
Documentation Menu

Quick Start (Go)

A high-performance Go implementation of the DTRules decision table rules engine.

Overview

The Go implementation provides:

  • Full compatibility with DTRules XML formats (EDD and Decision Tables)
  • High performance with zero-allocation hot paths
  • Dual execution modes: Object-based (compatible) and Value-based (optimized)
  • 179+ operators covering math, boolean, string, array, date, and control flow operations

Performance

Key optimizations achieve significant speedups:

Operation Baseline Optimized Speedup
Operator Lookup 83 ns 0.64 ns 130x
Integer Arithmetic 19 ns 0.79 ns 24x
String Creation 41 ns 11 ns 3.7x

Installation

go get github.com/dtrules/dtrules/go

Using the CLI

# Clone the repository
git clone https://github.com/dtrules/dtrules.git
cd DTRules/go

# Build the CLI
go build -o dtrules ./cmd/dtrules

# List decision tables
./dtrules -rules ../sampleprojects/CHIP/xml -list

# Validate rules
./dtrules -rules ../sampleprojects/CHIP/xml -validate

# Execute a decision table
./dtrules -rules ../sampleprojects/CHIP/xml -entry Compute_Eligibility

# Execute with tracing
./dtrules -rules ../sampleprojects/CHIP/xml -entry Main -trace

Using as a Library

package main

import (
    "os"
    "github.com/dtrules/dtrules/go/pkg/dtrules/session"
)

func main() {
    // Create a rule set
    rs := session.NewRuleSet("MyRules")

    // Load EDD (Entity Data Dictionary)
    eddFile, _ := os.Open("EDD.xml")
    rs.LoadEDD(eddFile)
    eddFile.Close()

    // Load Decision Tables
    dtFile, _ := os.Open("DecisionTables.xml")
    rs.LoadDecisionTables(dtFile)
    dtFile.Close()

    // Create a session and execute
    sess, _ := rs.NewSession()
    rsess := sess.(*session.RSession)
    rsess.Execute("Compute_Eligibility")
}

Architecture

DTRules uses a three-stack interpreter similar to PostScript:

  • Data Stack: Holds operands and intermediate values
  • Entity Stack: Provides scoped dictionary lookup (context)
  • Control Stack: Manages stack frames and local variables
┌─────────────────────────────────────────────┐
│              DTRules Runtime                │
├─────────────────────────────────────────────┤
│  Expression → Compiler → Executable Code    │
│                              │              │
│              ┌───────────────┼───────────┐  │
│              ▼               ▼           │  │
│       ┌───────────┐   ┌───────────┐      │  │
│       │  Object   │   │   Value   │      │  │
│       │   Stack   │   │   Stack   │      │  │
│       └───────────┘   └───────────┘      │  │
│              │               │           │  │
│              └───────┬───────┘           │  │
│                      ▼                   │  │
│               ┌───────────┐              │  │
│               │  Entity   │              │  │
│               │   Stack   │              │  │
│               └───────────┘              │  │
└─────────────────────────────────────────────┘

Package Structure

go/
├── cmd/
│   ├── dtrules/          # CLI tool
│   └── api/              # REST API server for UI
└── pkg/dtrules/
    ├── compiler/         # Postfix expression compiler
    ├── interpreter/      # State and bytecode VM
    ├── entity/           # Entity system
    ├── operators/        # 179+ built-in operators
    ├── session/          # Session and RuleSet management
    ├── decisiontable/    # Decision table execution
    ├── loader/           # XML loaders (EDD, DT)
    ├── mapping/          # Data mapping
    └── benchmark/        # Performance benchmarks

REST API Server

The API server provides HTTP endpoints for the DTRules UI:

# Start the API server (default port 8080)
go run ./cmd/api

# Start on a different port
go run ./cmd/api -port 9000

# With verbose logging
go run ./cmd/api -v

API Endpoints

Endpoint Method Description
/api/health GET Health check
/api/project/open POST Open project directory
/api/project/save POST Save modified files
/api/edd GET Get all entities
/api/dt GET/POST List/create decision tables
/api/execute POST Execute rules

Decision Table Types

  • BALANCED: All condition branches must be defined
  • FIRST: Executes only the first matching column
  • ALL: Executes all matching columns in order

Testing

# Run all tests
go test ./...

# Run benchmarks
go test -bench=. ./pkg/dtrules/benchmark/... -benchmem

# Run specific tests
go test -v ./pkg/dtrules -run TestValue

Next Steps