Mathematical Engines

Engines are the brain of Trezoriq. They are isolated, side-effect-free functions that handle all financial calculations with 100% deterministic results.

The Purity Mandate

To ensure reliability and testability, all engines must adhere to these rules:

No State

No React hooks or external state access.

No I/O

No API calls or localStorage inside engines.

No Time

All dates must be passed as arguments.

Financial Precision

JavaScript's native `number` type uses 64-bit floats, which leads to rounding errors (e.g., `0.1 + 0.2 !== 0.3`). Trezoriq solves this using the `Money` class.

// Always use Money class for calculations

import { Money } from '@/lib/utils/money';

export function calculateTax(income: number) {
  const mIncome = new Money(income);
  const taxRate = 0.30;
  
  return mIncome
    .multiply(taxRate)
    .add(400) // Cess
    .toRupees(); // Returns rounded number for UI
}

Testing Engines

Because engines are pure functions, they are extremely easy to unit test. Every engine in `src/tools/engines/` should have a corresponding `.test.ts` file in `src/__tests__/engines/`.

File Organization

Engines are stored in `src/tools/engines/[pillar]/`.

src/tools/engines/grow/sip-calculator.tscontains export function calculateSIP()