08 Financial System

08. Financial System & Integer-Cents Arithmetic

Architectural specification for the pure integer-cents financial discipline engine in src/lib/money.ts.

---

⚡ The Zero-Float Financial Rule

PACT OS strictly forbids floating-point arithmetic for currency calculations:

// ❌ FORBIDDEN IN PACT OS: Floating-point precision error
0.1 + 0.2 // 0.30000000000000004

// ✅ MANDATORY IN PACT OS: Integer-cents calculations
10 + 20 // 30 cents ($0.30)

Floating-point numbers in JavaScript suffer from binary representation inaccuracies (IEEE 754 standard). In PACT OS, all monetary amounts are converted to and stored as integer cents (amount_cents of type bigint in PostgreSQL / number in TypeScript).

---

🧮 Core Functions in src/lib/money.ts

1. parseAmountToCents(input: string | number)

Parses user-entered currency strings or numbers safely into integer cents:

• Handles inputs like "45", "45.50", "1,250.00", "₹1200".
• Strips non-numeric characters while preserving valid decimal points.
• Enforces positive amount validation and threshold bounds.

import { parseAmountToCents } from '@/lib/money';

const res = parseAmountToCents("45.99");
// Returns: { cents: 4599, error: null }

2. formatCentsToCurrency(cents: number, currencyCode = 'INR', options?: ...)

Formats integer cents into a localized currency string using Intl.NumberFormat:

import { formatCentsToCurrency } from '@/lib/money';

formatCentsToCurrency(4999, 'USD'); // "$49.99"
formatCentsToCurrency(150000, 'INR', { showFractional: false }); // "₹1,500"

3. Metric Computation Engines

• calculateFinanceSummary(transactions): Computes total income cents, total expense cents, net savings cents, savings rate percentage, and total transaction count.
• calculateCategoryBreakdown(transactions, categories): Aggregates expense totals per category with percentage rollups.
• calculateMonthlyTrends(transactions, timeZone): Computes historical month-over-month cashflow metrics.

---

📊 Budget Envelope Architecture

graph TD
    Trans[New Expense Transaction] --> Parse[parseAmountToCents]
    Parse --> DB[(Store amount_cents in PostgreSQL)]
    DB --> Agg[calculateCategoryBreakdown]
    Agg --> BudgetCheck{Compare totalCents vs limitCents}
    BudgetCheck -->|Below Limit| Normal[Normal Category Status]
    BudgetCheck -->|Exceeds Limit| Alert[Budget Exceeded Warning]

Loading

• Each category budget specifies a limit_cents threshold.
• Budget utilization percentages are calculated dynamically from integer cents without rounding drift.