Tax Brackets & Config

The Tax Brackets & Config module serves as the financial intelligence layer of the Rosy Tax Processor. It manages the static data and logic required to transform raw income data into estimated federal tax liabilities. This system centralizes tax rate definitions, standard deductions, and field mapping configurations to ensure consistent calculations across the application.

This module interacts closely with the document extraction pipeline to receive validated income figures and provides the necessary data for the final PDF generation process.

Tax Calculation Architecture

The tax calculation engine uses a progressive tax bracket model. It supports multiple filing statuses, primarily "Single" and "Married," which dictate both the standard deduction applied and the specific tax brackets used for calculation.

Calculation Logic Flow

The engine first aggregates income from various sources (W-2, 1099), subtracts the applicable standard deduction to determine taxable income, and then iterates through progressive brackets to calculate the gross tax.

The logic for determining the final tax due involves subtracting the total withholding (aggregated from document fields or user input) from the gross calculated tax.
Sources: taxcalc.py:10-85, pipeline.py:65-85

Data Structures & Configuration

Standard Deductions

Standard deductions are hardcoded as a dictionary for demonstration purposes. These values are subtracted from the Adjusted Gross Income (AGI) to reach the taxable income.

Sources: taxcalc.py:11-14

Progressive Brackets

Brackets are loaded from an external tax_brackets.json file. Each bracket defines an upper limit (upto) and a marginal tax rate. If the external file is missing, the system defaults to a minimal internal set.

{
    "single": [
        {"upto": 11000.0, "rate": 0.10},
        {"upto": 44725.0, "rate": 0.12},
        {"upto": 95375.0, "rate": 0.22},
        {"upto": 182100.0, "rate": 0.24}
    ]
}

Sources: taxcalc.py:17-41

Field Mapping Configuration

To ensure extracted data is correctly placed into the Form 1040 template, the system uses a configuration file and a mapping utility.

1040 Field Reference

The file templates/1040_fields.json contains the technical AcroForm field names used by the fillable PDF template.

Sources: templates/1040_fields.json:1-17

Exact Mapping Logic

The forms.py module contains an exact mapping dictionary that links internal pipeline keys to the 1040 template fields.

Integration with Pipeline

The configuration data is consumed during the finalize stage of the processing pipeline. The backend aggregates the final edited fields from the frontend, executes the calculation estimate, and passes the results to the form filler.

The system provides high accuracy for tax estimation by separating the calculation data (JSON) from the logic (Python), allowing for easier updates to tax laws without modifying core code.