Tax Estimation Logic

The Tax Estimation module provides users with a projected breakdown of their annual tax liability and net take-home pay. Unlike static tax calculators, this system utilizes a Generative AI service to interpret location-specific tax laws and filing statuses in real-time.

The Tax Estimation Service

The core logic resides in services/geminiService.ts. The system uses the gemini-3-flash-preview model to process financial inputs and return structured JSON data.

Function: getTaxEstimate

This asynchronous function is the primary entry point for tax calculations. It sends a structured prompt to the AI agent, including safety protocols to ensure the response remains educational rather than professional legal advice.

export const getTaxEstimate = async (
  income: number,
  location: string,
  filingStatus: string
): Promise<TaxEstimate>

Parameters:

• income (number): The annual gross income (Power).
• location (string): The user's state or region (e.g., "California", "New York").
• filingStatus (string): The legal filing status (e.g., "Single", "Married Filing Jointly").

Data Structure: TaxEstimate

The service returns a TaxEstimate object, defined in types.ts, which includes both quantitative data and qualitative advice.

| Property | Type | Description | | :--- | :--- | :--- | | estimatedTax | number | The total projected tax liability. | | effectiveRate | number | The percentage of income paid in taxes (0.0 to 1.0). | | takeHomePay | number | The remaining annual income after taxes. | | bracket | string | The highest marginal tax bracket applicable (e.g., "22%"). | | tips | string[] | AI-generated suggestions for tax optimization (e.g., "Maximize 401k"). |

Implementation Example

To use the tax estimation logic within a component, import the service and manage the resulting state as shown below:

import { getTaxEstimate } from '../services/geminiService';
import { TaxEstimate } from '../types';

const handleTaxCalculation = async () => {
  try {
    const results: TaxEstimate = await getTaxEstimate(
      100000, 
      "Texas", 
      "Single"
    );
    console.log(`Estimated Take Home: $${results.takeHomePay}`);
  } catch (error) {
    console.error("Failed to fetch tax projection", error);
  }
};

AI Logic & Safety Protocols

The estimation engine is governed by a strict system prompt to ensure consistency and reliability:

1. JSON Enforcement: The engine is instructed to return only a valid JSON object, which is then parsed via a cleanJson helper to strip any Markdown formatting.
2. Safety Disclaimer: Every request includes a SAFETY_DISCLAIMER. If the user attempts to solicit advice on illegal tax evasion, the system is programmed to redirect them to a certified professional.
3. Contextual Awareness: The prompt instructs the model to factor in standard deductions and state-specific income tax rates based on the location string provided.

Logic Verification

The accuracy and resilience of the tax logic are validated through the Jest test suite in __tests__/geminiService.test.ts.

Tests cover:

• Functional Integrity: Ensuring the API correctly maps inputs to the expected TaxEstimate fields.
• Resilience: Verifying that the application returns a safe default object even if the AI service encounters a 500 error or a network failure.