DTRules
Documentation Menu

Quick Start (Tax Return)

The TaxReturn sample project demonstrates DTRules handling enterprise-scale regulatory complexity with 139+ decision tables covering federal income tax, 40+ IRS forms, and multiple state taxes.

Demonstration Project

This tax implementation demonstrates DTRules' production-grade technology but is not certified for actual tax filing. Use for learning and evaluation purposes.

Quick Start (5 minutes)

Prerequisites

  • Go 1.21+ installed
  • Git for cloning the repository

Step 1: Clone the Repository

git clone https://github.com/DTRules/DTRules.git
cd DTRules

Step 2: Run a Simple Tax Calculation

# Navigate to the Go directory
cd go

# Run the simple tax return test
go test ./pkg/dtrules/... -run TestTaxReturn_Simple -v

Step 3: View Results

The test output shows the calculated values including AGI, standard deduction, taxable income, and total tax liability.

Step 4: Run with Trace

# Build the CLI with trace support
cd go/cmd/dtrules
go build -o dtrules

# Run with full execution trace
./dtrules -rules ../../sampleprojects/TaxReturn/xml \
  -entry Compute_Tax_Return \
  -trace \
  -input ../../sampleprojects/TaxReturn/testfiles/TestScenarios/Level1/TestCase_L1_Simple.xml

Project Structure

sampleprojects/TaxReturn/
├── xml/
│   ├── TaxReturn_edd.xml       # Entity definitions (taxpayer, job, result)
│   ├── TaxReturn_dt.xml        # Federal decision tables (139+)
│   ├── TaxReturn_map.xml       # XML to entity mapping
│   └── states/                 # State-specific files
│       ├── CA_edd.xml          # California constants
│       ├── CA_dt.xml           # California decision tables
│       ├── CO_edd.xml          # Colorado constants
│       ├── CO_dt.xml           # Colorado decision tables
│       └── ...                 # Other states
├── testfiles/
│   └── TestScenarios/          # Test cases
│       ├── Level1/             # Simple W-2 returns
│       ├── Level2/             # Family returns with credits
│       └── Comprehensive/      # Complex multi-form returns
└── docs/                       # Documentation

Understanding the Implementation

How a Tax Calculation Works

  1. Input: Test scenario XML file (taxpayer data, W-2s, deductions)
  2. Mapping: TaxReturn_map.xml transforms XML into entities
  3. Execution: Decision tables execute in sequence
  4. Output: Result entity with all calculated values

Decision Table Flow

Table 1000: Compute_Tax_Return (entry point)
  |
  +-> Table 2000: Calculate_AGI
  |     |
  |     +-> Table 2100: Process_W2_Income
  |     +-> Table 2200: Process_Self_Employment
  |     +-> Table 2300: Process_Rental_Income
  |
  +-> Table 2500: Calculate_Deductions
  |     |
  |     +-> Table 2510: Calculate_Standard_Deduction
  |     +-> Table 2520: Calculate_Itemized_Deductions
  |
  +-> Table 3000: Calculate_Tax_Liability
  |     |
  |     +-> Table 3100: Apply_Tax_Brackets_Single
  |     +-> Table 3110: Apply_Tax_Brackets_MFJ
  |     +-> Table 3120: Apply_Tax_Brackets_HOH
  |
  +-> Table 3500: Calculate_Credits
  |     |
  |     +-> Table 3510: Calculate_Child_Tax_Credit
  |     +-> Table 3520: Calculate_EITC
  |     +-> Table 3530: Calculate_Education_Credits
  |
  +-> Table 4000: Dispatch_State_Tax
        |
        +-> Table 40100: Calculate_CA_Tax
        +-> Table 40200: Calculate_CO_Tax
        +-> ...

Running Different Scenarios

Simple W-2 Return

go test ./pkg/dtrules/... -run TestCase_L1_Simple -v

Family with Children (CTC/EITC)

go test ./pkg/dtrules/... -run TestCase_Family_2025 -v

Self-Employed (Schedule C)

go test ./pkg/dtrules/... -run TestCase_C02_Self_Employed -v

All Tax Return Tests

go test ./pkg/dtrules/... -run TestTaxReturn -v

Example: Standard Deduction Decision Table

Here's how the standard deduction is encoded as a decision table: 

<decision_table>
  <table_name>Calculate_Standard_Deduction</table_name>
  <attribute_fields>
    <Type>FIRST</Type>
    <COMMENTS>Form 1040 Line 12 - Standard Deduction
    Ref: IRC Section 63(c)(2), Publication 17 Chapter 5</COMMENTS>
  </attribute_fields>

  <conditions>
    <condition id="1">result.filing_status eq 'single'</condition>
    <condition id="2">result.filing_status eq 'mfj'</condition>
    <condition id="3">result.filing_status eq 'hoh'</condition>
  </conditions>

  <actions>
    <action id="1">set result.standard_deduction = standard_deduction_single</action>
    <action id="2">set result.standard_deduction = standard_deduction_mfj</action>
    <action id="3">set result.standard_deduction = standard_deduction_hoh</action>
  </actions>

  <columns>
    <column id="single">
      <condition ref="1">Y</condition>
      <condition ref="2">N</condition>
      <condition ref="3">N</condition>
      <action ref="1">X</action>
    </column>
    <column id="mfj">
      <condition ref="1">N</condition>
      <condition ref="2">Y</condition>
      <condition ref="3">N</condition>
      <action ref="2">X</action>
    </column>
    <column id="hoh">
      <condition ref="1">N</condition>
      <condition ref="2">N</condition>
      <condition ref="3">Y</condition>
      <action ref="3">X</action>
    </column>
  </columns>
</decision_table>

Common Tasks

Add a New Test Case

  1. Copy an existing scenario XML from testfiles/TestScenarios/
  2. Modify income, deductions, and credits as needed
  3. Run: go test -run YourTestName -v

Modify a Tax Calculation

  1. Find the relevant decision table in xml/TaxReturn_dt.xml
  2. Update the condition or action
  3. Run tests to verify the change
  4. Check output for correctness

Add a New State

  1. Copy templates: cp xml/states/TEMPLATE_*.xml xml/states/XX_*.xml
  2. Add state constants to XX_edd.xml
  3. Add decision tables to XX_dt.xml
  4. Run merge script: ./scripts/merge-states.sh
  5. Add test cases in testfiles/TestScenarios/State/XX/

Performance

The Go implementation achieves impressive tax calculation speeds:

Scenario Processing Time Throughput (single core)
Simple W-2 Return ~250 us ~4,000/sec
Family (CTC/EITC) ~390 us ~2,500/sec
Self-Employed ~520 us ~1,900/sec
Complex Multi-State ~1.2 ms ~830/sec

Traceability

Every calculation includes full audit trail linking back to IRS forms and publications:

  • Form References: Form 1040 Line 12, Schedule A, etc.
  • Publication Citations: Pub 17 Chapter 5, Pub 501, etc.
  • IRC Sections: IRC 63(c)(2), IRC 1(a), etc.
  • Revenue Procedures: Rev. Proc. 2024-40 for current year values

Coverage

Federal Forms (40+)

  • Form 1040: Individual Income Tax Return
  • Schedule A: Itemized Deductions
  • Schedule C: Business Income
  • Schedule D: Capital Gains
  • Schedule E: Rental/Passive Income
  • Schedule SE: Self-Employment Tax
  • Form 6251: Alternative Minimum Tax
  • Schedule 8812: Child Tax Credit
  • And 32+ more forms...

State Taxes (11 implemented)

  • California (CA) - Progressive rates with high-income surcharge
  • Colorado (CO) - Flat rate 4.4%
  • Connecticut (CT) - Progressive rates
  • Illinois (IL) - Flat rate 4.95%
  • Indiana (IN) - Flat rate with county adjustments
  • Michigan (MI) - Flat rate with city taxes
  • Minnesota (MN) - Progressive rates
  • Montana (MT) - Progressive rates
  • New Hampshire (NH) - Interest/dividends only
  • North Carolina (NC) - Flat rate
  • Pennsylvania (PA) - Flat rate 3.07%

Next Steps