Building 9 Tax Analysis Engines: Inside Atlas Finance's Bracket Stacking Architecture

Building 9 Tax Analysis Engines: Inside Atlas Finance's Bracket Stacking Architecture

When I started building Atlas Finance's tax calculator, I knew I couldn't just throw together a simple income × rate calculation and call it a day. The US tax code is incredibly complex, and I wanted users to get insights that actually matter — not just "you owe $X in taxes."

After months of iteration, I ended up with something I'm really proud of: 9 specialized tax analysis engines that work together to provide comprehensive tax insights. Today, I want to walk you through how this system works under the hood.

The Engine Architecture

Each engine has a specific scope of analysis and operates independently before coordinating with others. Here's the full lineup:

• W-2 Engine: Processes wage income, analyzes withholdings vs. liability
• 401k/IRA Engine: Handles retirement contributions and withdrawal tax implications
• Deductions Engine: Itemized vs. standard deduction optimization
• Loans Engine: Student loan interest, mortgage interest calculations
• Side Hustle Engine: Freelance income detection and self-employment tax
• HSA Engine: Contribution limits, tax advantages, withdrawal penalties
• Investments Engine: Capital gains/losses, dividend taxation
• Credits Engine: Child tax credit, EITC, education credits optimization
• Filing Status Engine: Married filing jointly vs. separately analysis

What makes this architecture powerful is how the engines coordinate. They don't just run in isolation — they pass data between each other and build on previous calculations.

Real-Time Status Cycling

One of my favorite UX touches is the real-time status messages that cycle while the engines run. Each engine broadcasts its current state, creating this sense that the system is actively working through your tax situation:

const EngineStatusCycler = ({ engines }: { engines: TaxEngine[] }) => {
  const [currentIndex, setCurrentIndex] = useState(0);
  const [displayedStatus, setDisplayedStatus] = useState('');

  useEffect(() => {
    const interval = setInterval(() => {
      const activeEngines = engines.filter(e => e.status !== 'completed');
      if (activeEngines.length === 0) return;

      const currentEngine = activeEngines[currentIndex % activeEngines.length];
      const statusMessages = {
        'analyzing': `Analyzing ${currentEngine.name}...`,
        'processing': `Processing ${currentEngine.scope}`,
        'calculating': `Running ${currentEngine.name} calculations`,
        'optimizing': `Optimizing ${currentEngine.name} strategy`
      };

      setDisplayedStatus(statusMessages[currentEngine.status] || currentEngine.status);
      setCurrentIndex(prev => prev + 1);
    }, 1200);

    return () => clearInterval(interval);
  }, [engines, currentIndex]);

  return (
    <div className="flex items-center space-x-2 text-sm text-gray-600">
      <div className="animate-spin h-4 w-4 border-2 border-blue-500 border-t-transparent rounded-full" />
      <span className="transition-all duration-300">{displayedStatus}</span>
    </div>
  );
};

This creates a really satisfying experience where users can see messages like "Analyzing Side Hustle income..." → "Processing investment gains..." → "Optimizing deduction strategy..." as the system works.

Engine Coordination: Side Hustle → Filing

The coordination between engines is where the real magic happens. Take the Side Hustle engine as an example. It doesn't just calculate self-employment tax — it passes crucial data downstream:

1. Side Hustle Engine detects 1099 income from connected bank accounts
2. Calculates self-employment tax (15.3% on net earnings)
3. Determines if quarterly estimated payments are required
4. Passes estimated payment schedule to Filing Status Engine
5. Filing engine then factors this into refund/payment projections

This coordination prevents the common mistake of calculating income tax correctly but missing the quarterly payment requirements that could result in penalties.

The HSA engine works similarly — it calculates contribution limits based on your health plan type (detected from payroll data), then passes the tax-deductible contribution amount to the W-2 engine to adjust your effective tax rate.

Bracket Stacking: The Technical Challenge

The most complex part of the system is implementing bracket stacking correctly. This is where ordinary income fills tax brackets first, then preferential income (like long-term capital gains) gets layered on top at preferential rates.

Here's how I handle it:

interface TaxBracket {
  min: number;
  max: number;
  rate: number;
}

class BracketStackingCalculator {
  calculateTax(ordinaryIncome: number, preferentialIncome: number, brackets: TaxBracket[]) {
    // Step 1: Fill brackets with ordinary income
    let ordinaryTax = 0;
    let remainingOrdinary = ordinaryIncome;
    let topBracketStart = 0;

    for (const bracket of brackets) {
      if (remainingOrdinary <= 0) break;
      
      const bracketWidth = bracket.max - bracket.min;
      const taxableInThisBracket = Math.min(remainingOrdinary, bracketWidth);
      
      ordinaryTax += taxableInThisBracket * bracket.rate;
      remainingOrdinary -= taxableInThisBracket;
      
      if (remainingOrdinary > 0) {
        topBracketStart = bracket.max;
      }
    }

    // Step 2: Layer preferential income on top
    const preferentialRates = this.getPreferentialRates(topBracketStart + preferentialIncome);
    const preferentialTax = preferentialIncome * preferentialRates.capitalGains;

    return {
      ordinaryTax,
      preferentialTax,
      totalTax: ordinaryTax + preferentialTax,
      effectiveRate: (ordinaryTax + preferentialTax) / (ordinaryIncome + preferentialIncome)
    };
  }
}

This ensures that a high earner's capital gains don't get taxed at 0% just because their ordinary income pushes them into higher brackets. The preferential income sits "on top" of the ordinary income stack.

Contextual Insights Generation

Each engine doesn't just crunch numbers — it generates contextual insights based on the analysis. The Investments engine, for example, might detect that you're close to the long-term capital gains rate threshold and suggest timing strategies:

"Your taxable income is $170,000. Consider realizing capital gains before year-end — you have $363,400 of room remaining in the 15% capital gains bracket before hitting the 20% rate."

The Credits engine might notice unused education credits:

"You paid $8,000 in qualified education expenses but only claimed $2,500 in credits. You may be eligible for the American Opportunity Tax Credit."

These insights are generated by each engine's analysis patterns and business logic, not generic templates.

Performance and Reliability

With 9 engines running complex calculations, performance was a concern. I implemented a few key optimizations:

• Lazy evaluation: Engines only run when their input data changes
• Memoization: Complex bracket calculations are cached
• Progressive enhancement: Basic tax estimates show immediately, detailed analysis streams in
• Error isolation: If one engine fails, others continue running

The result is a system that feels fast and reliable, even when processing complex tax scenarios with multiple income sources and deductions.

What's Next

I'm currently working on two major additions: a Crypto engine for digital asset taxation and a State Tax engine that handles multi-state scenarios. The beauty of this architecture is that new engines plug right into the existing coordination system.

The tax calculator has become one of Atlas Finance's most-used features, and seeing users catch tax optimization opportunities they would have missed makes all the complexity worth it. Sometimes the best user experiences are built on the most intricate technical foundations.