TaxReturn Example

The TaxReturn sample project demonstrates DTRules at scale, implementing complete federal income tax calculation plus all 50 states and DC. This guide walks through the project structure, key decision tables, and implementation patterns.

Project Overview

TaxReturn implements the full Form 1040 calculation including:

Gross income from all sources (W-2, self-employment, rental, investments)
Deductions (standard and itemized, including SALT cap)
Tax bracket calculation for all filing statuses
Alternative Minimum Tax (AMT)
Tax credits (Child Tax Credit, EITC, education credits)
State income tax for all 50 states + DC

Project Structure

sampleprojects/TaxReturn/
  xml/
    TaxReturn_edd.xml         # Entity Data Dictionary (data model)
    TaxReturn_dt.xml          # Decision Tables (rules)
    TaxReturn_map.xml         # Input/output mapping
    states/
      CA_edd.xml              # California-specific entities
      CA_dt.xml               # California tax tables
      NY_edd.xml              # New York-specific entities
      NY_dt.xml               # New York tax tables
      ... (all 50 states + DC)
  testfiles/
    TestScenarios/            # Test cases by scenario

Entity Data Dictionary

The EDD defines the data model for tax returns. Here's the core job entity:

<entity name="job" comment="Root entity for tax return processing">
  <field name="tax_year" type="integer" default_value="2025"
         comment="Tax year being processed" />
  <field name="filing_status" type="string"
         comment="Filing status: MFJ, MFS, Single, HOH, QSS" />
  <field name="state" type="string" default_value="TX"
         comment="State of residence" />
  <field name="taxpayers" type="array" subtype="taxpayer"
         comment="Taxpayers on this return" />
  <field name="dependents" type="array" subtype="dependent"
         comment="Dependents on this return" />
  <field name="results" type="array" subtype="result"
         comment="Results of tax calculation" />
  <field name="audit_trail" type="array"
         comment="Detailed trace of every decision" />
</entity>

Key Entities

Entity	Purpose
`job`	Root entity containing all tax return data
`taxpayer`	Individual taxpayer (primary and spouse)
`dependent`	Dependent children and qualifying relatives
`result`	Calculated results (AGI, taxable income, tax, etc.)
`property`	Real estate for Schedule A/E
`income`	Income sources (wages, investments, etc.)

Decision Table Structure

The main entry point is Compute_Tax_Return, which orchestrates all calculations following the Form 1040 structure:

<decision_table>
  <table_name>Compute_Tax_Return</table_name>
  <attribute_fields>
    <Type>FIRST</Type>
    <COMMENTS>Entry point for tax return calculation.
    Orchestrates the complete tax calculation process
    following the structure of Form 1040.</COMMENTS>
    <TABLE_NUMBER>1000</TABLE_NUMBER>
  </attribute_fields>

  <conditions>
    <condition>job.filing_status = "MFJ"</condition>
    <condition>job.filing_status = "Single"</condition>
    <condition>job.filing_status = "HOH"</condition>
    <condition>otherwise</condition>
  </conditions>

  <actions>
    <!-- Calculate gross income (Form 1040 Lines 1-9) -->
    <action>Calculate_Gross_Income</action>

    <!-- Calculate deductions (Form 1040 Line 12) -->
    <action>Calculate_Deductions</action>

    <!-- Calculate taxable income (Form 1040 Line 15) -->
    <action>Calculate_Taxable_Income</action>

    <!-- Calculate tax liability (Form 1040 Lines 16-24) -->
    <action>Calculate_Tax_Liability</action>

    <!-- Calculate credits (Form 1040 Lines 19-21) -->
    <action>Calculate_Credits</action>

    <!-- Calculate final balance (Form 1040 Lines 33-37) -->
    <action>Calculate_Final_Balance</action>

    <!-- State tax if applicable -->
    <action>if job.has_state_income_tax then Dispatch_State_Tax</action>
  </actions>
</decision_table>

Tax Bracket Example

The Apply_Tax_Brackets_MFJ table demonstrates how progressive tax brackets are implemented. It uses FIRST type to find the applicable bracket:

<decision_table>
  <table_name>Apply_Tax_Brackets_MFJ</table_name>
  <attribute_fields>
    <Type>FIRST</Type>
    <COMMENTS>Applies 2025 tax brackets for Married Filing Jointly
    per IRC Section 1(a) and Rev. Proc. 2024-40</COMMENTS>
  </attribute_fields>

  <!-- 2025 MFJ Tax Brackets -->
  <conditions>
    <!-- 10% bracket: $0 - $23,850 -->
    <condition>result.taxable_income <= 23850</condition>
    <!-- 12% bracket: $23,850 - $96,950 -->
    <condition>result.taxable_income <= 96950</condition>
    <!-- 22% bracket: $96,950 - $206,700 -->
    <condition>result.taxable_income <= 206700</condition>
    <!-- 24% bracket: $206,700 - $394,600 -->
    <condition>result.taxable_income <= 394600</condition>
    <!-- 32% bracket: $394,600 - $501,050 -->
    <condition>result.taxable_income <= 501050</condition>
    <!-- 35% bracket: $501,050 - $751,600 -->
    <condition>result.taxable_income <= 751600</condition>
    <!-- 37% bracket: over $751,600 -->
    <condition>otherwise</condition>
  </conditions>

  <actions>
    <action>set result.tax = result.taxable_income * 0.10</action>
    <action>set result.tax = 2385 + (result.taxable_income - 23850) * 0.12</action>
    <action>set result.tax = 11157 + (result.taxable_income - 96950) * 0.22</action>
    <action>set result.tax = 35302 + (result.taxable_income - 206700) * 0.24</action>
    <action>set result.tax = 80398 + (result.taxable_income - 394600) * 0.32</action>
    <action>set result.tax = 114462 + (result.taxable_income - 501050) * 0.35</action>
    <action>set result.tax = 202154.50 + (result.taxable_income - 751600) * 0.37</action>
  </actions>
</decision_table>

State Tax Implementation

Each state has its own EDD and decision table files. The Dispatch_State_Tax table routes to the appropriate state calculator:

<decision_table>
  <table_name>Dispatch_State_Tax</table_name>
  <Type>FIRST</Type>

  <conditions>
    <condition>job.state = "CA"</condition>
    <condition>job.state = "NY"</condition>
    <condition>job.state = "TX"</condition>
    <!-- ... more states ... -->
  </conditions>

  <actions>
    <action>Calculate_CA_Tax</action>
    <action>Calculate_NY_Tax</action>
    <action>-- no state income tax --</action>
  </actions>
</decision_table>

California Example

California uses a progressive bracket system similar to federal, with its own rates:

<!-- CA_edd.xml - California-specific constants -->
<entity name="result">
  <field name="ca_standard_deduction_single" type="double"
         default_value="5540" comment="CA standard deduction single 2025" />
  <field name="ca_standard_deduction_mfj" type="double"
         default_value="11080" comment="CA standard deduction MFJ 2025" />
</entity>

<!-- CA_dt.xml - California tax calculation -->
<decision_table>
  <table_name>Calculate_CA_Tax</table_name>
  <Type>FIRST</Type>

  <conditions>
    <condition>ca_taxable_income <= 10756</condition>
    <condition>ca_taxable_income <= 25499</condition>
    <!-- ... brackets continue to 13.3% top rate ... -->
  </conditions>
</decision_table>

Running the Example

With Go

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

With Java

cd java
mvn test -Dtest=TaxReturnTest

Key Design Patterns

1. Table Orchestration

The main table calls sub-tables for each major section. This keeps tables focused and makes testing easier.

2. Constants in EDD

Tax rates, bracket thresholds, and deduction limits are defined in the EDD with default values. This makes updating for new tax years straightforward.

3. Audit Trail

Every decision adds entries to the audit_trail array, providing complete transparency for compliance and debugging.

4. Modular State Files

Each state gets separate EDD and DT files to avoid merge conflicts and enable parallel development.

Performance

The Go runtime processes the TaxReturn project at production speeds:

15,000+ returns/second - Single-threaded throughput
<1ms latency - For complex returns with state tax
Zero allocations - In the hot path execution