DTRules
Documentation Menu

CHIP Tutorial

The CHIP (Children's Health Insurance Program) sample project demonstrates how DTRules handles real-world eligibility determination. This tutorial walks through the key components.

Project Overview

CHIP is a US federal program that provides health insurance coverage to children in families with incomes too high to qualify for Medicaid but too low to afford private coverage. The sample project implements eligibility rules similar to actual state systems.

Project Structure

sampleprojects/CHIP/
├── DecisionTables/
│   └── ChipEligibility_dt.xls    # Decision tables
├── edd/
│   └── ChipEligibility_edd.xls   # Entity definitions
├── xml/                           # Compiled XML (generated)
│   ├── ChipEligibility_edd.xml
│   └── ChipEligibility_dt.xml
├── testfiles/                     # Test cases
├── DTRules.xml                    # Configuration
└── src/main/java/
    ├── CompileChip.java           # Excel → XML compiler
    └── TestChip.java              # Test runner

Entity Data Dictionary

The CHIP EDD defines entities for:

Application

The main container for an eligibility application:

Entity: Application
  - household: Household
  - application_date: date
  - status: string
  - eligible_children: array of Person
  - benefit_amount: decimal

Household

Represents a family unit:

Entity: Household
  - head: Person
  - members: array of Person
  - address: string
  - state: string
  - total_income: decimal
  - household_size: integer

Person

Individual household members:

Entity: Person
  - name: string
  - birth_date: date
  - age: integer
  - ssn: string
  - citizen: boolean
  - income: decimal
  - relationship: string
  - eligible: boolean
  - reason_code: string

Context

Global configuration and thresholds:

Entity: Context
  - today: date
  - federal_poverty_level: decimal
  - max_income_percentage: decimal  // e.g., 200% of FPL
  - min_age: integer                // 0
  - max_age: integer                // 19

Decision Tables

The CHIP project includes several decision tables:

Main Entry Point

// Main orchestrates the eligibility determination
Table: Main
Type: FIRST

Actions:
  - perform Calculate_Household_Income
  - perform Determine_FPL_Percentage
  - for each member in household.members do
      perform Check_Child_Eligibility
    done
  - perform Summarize_Results

Calculate Household Income

// Sum all member incomes
Table: Calculate_Household_Income
Type: ALL

Action:
  set household.total_income = 0
  for each member in household.members do
    set household.total_income = household.total_income + member.income
  done

Check Child Eligibility

// Determine if a specific child qualifies
Table: Check_Child_Eligibility
Type: BALANCED

Conditions:
  1. member.age >= min_age and member.age <= max_age
  2. member.citizen = true
  3. fpl_percentage <= max_income_percentage

Condition  R1  R2  R3  R4  R5  R6  R7  R8
Age OK      Y   Y   Y   Y   N   N   N   N
Citizen     Y   Y   N   N   Y   Y   N   N
Income OK   Y   N   Y   N   Y   N   Y   N
Eligible    X   -   -   -   -   -   -   -
Age Fail    -   -   -   -   X   X   X   X
Cit Fail    -   -   X   X   -   -   -   -
Inc Fail    -   X   -   -   -   -   -   -

Actions:
  - set member.eligible = true
  - set member.reason_code = "age_ineligible"
  - set member.reason_code = "not_citizen"
  - set member.reason_code = "income_too_high"

Summarize Results

// Collect eligible children and calculate benefits
Table: Summarize_Results
Type: ALL

Actions:
  for each member in household.members do
    if member.eligible then
      add member to application.eligible_children
    fi
  done
  set application.benefit_amount =
    count of application.eligible_children * monthly_benefit_per_child

Running the Example

Using the Visual UI

  1. Start the backend: cd go && go run ./cmd/api
  2. Start the UI: cd ui && npm run dev
  3. Open http://localhost:5173
  4. Click "Start Tutorial" or "Open Sample Project"
  5. Explore the entities in the left panel
  6. Click on decision tables to view them
  7. Use the Test tab to run test cases

Using the CLI

cd go

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

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

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

Using Java

cd sampleprojects/CHIP

# Compile Excel to XML (if needed)
mvn exec:java -Dexec.mainClass="com.dtrules.samples.chipeligibility.CompileChip"

# Run test cases
mvn exec:java -Dexec.mainClass="com.dtrules.samples.chipeligibility.TestChip"

Test Cases

The CHIP project includes test cases that verify different scenarios:

Test Case 1: Eligible Family

// Household with one eligible child
{
  "household": {
    "total_income": 25000,
    "members": [
      { "name": "Parent", "age": 35, "citizen": true },
      { "name": "Child", "age": 8, "citizen": true }
    ]
  },
  "federal_poverty_level": 15000,
  "max_income_percentage": 200
}

// Expected: Child is eligible (income is 167% of FPL, under 200%)

Test Case 2: Income Too High

// Household over income limit
{
  "household": {
    "total_income": 45000,
    "members": [
      { "name": "Parent", "age": 35, "citizen": true },
      { "name": "Child", "age": 8, "citizen": true }
    ]
  },
  "federal_poverty_level": 15000,
  "max_income_percentage": 200
}

// Expected: Child not eligible (income is 300% of FPL, over 200%)

Test Case 3: Age Ineligible

// Child too old for CHIP
{
  "household": {
    "members": [
      { "name": "Parent", "age": 45, "citizen": true },
      { "name": "Adult Child", "age": 21, "citizen": true }
    ]
  }
}

// Expected: Not eligible (age 21 > max_age 19)

Key Concepts Demonstrated

Entity Relationships

The CHIP model shows one-to-many relationships (Household → Members) and how to iterate through related entities.

BALANCED vs FIRST Tables

The eligibility check uses a BALANCED table to ensure every scenario is explicitly handled. The main orchestration uses FIRST/ALL for flow control.

Calculated Values

Household income and FPL percentage are calculated from input data, showing how DTRules handles derived values.

Tracing

Running with -trace shows exactly how each decision is made, demonstrating DTRules' auditability.

Next Steps