Day 17: Money Speaks Many Languages

Most finance apps handle multiple currencies by silently converting everything to a "base currency." Your EUR account shows a USD equivalent. Your reports aggregate everything in dollars. The conversion happens behind the scenes, using rates you didn't choose, at times you don't know about.

We took a different path: no hidden conversions, no automatic rate fetching, no implicit base currency. Every currency stands on its own terms.

The Core Principles

Our multi-currency implementation follows strict principles:

• Local-first, offline-capable: No external APIs. No rate fetching. Works without internet.
• User-controlled rates: You enter exchange rates. You decide when they're effective.
• No hidden base currency: USD doesn't dominate. All currencies are peers.
• Explicit conversion: When conversion happens, you see it. Rate, date, direction—all visible.
• Transactions never mutate: The ledger stays pure. Conversion is always a view concern.

The Architecture: Layers of Truth

We extended our layered architecture. The ledger (truth layer) remains currency-pure. Conversion lives in the view layer:

┌─────────────────────────────────────────────┐
│              VIEW LAYER                      │
│   QueryEngine.executeWithConversion()        │
│   CurrencyAmount component                   │
│   Multi-currency totals (derived)            │
└─────────────────────────────────────────────┘
                    │
                    │ reads rates, converts on-demand
                    ▼
┌─────────────────────────────────────────────┐
│           EXCHANGE RATE LAYER                │
│   User-provided rates                        │
│   Effective-at timestamps                    │
│   Inverse rate computation                   │
└─────────────────────────────────────────────┘
                    │
                    │ never modifies
                    ▼
┌─────────────────────────────────────────────┐
│              TRUTH LAYER                     │
│   LedgerService (currency-pure)              │
│   Transactions always in original currency   │
└─────────────────────────────────────────────┘

Exchange Rates: Explicit and Historical

Each exchange rate has an effectiveAt timestamp. When you need a rate for January 15th, we find the most recent rate effective on or before that date.

// Exchange rate semantics
interface ExchangeRate {
  fromCurrency: 'USD';
  toCurrency: 'EUR';
  rate: 0.85;              // 1 USD = 0.85 EUR
  effectiveAt: 1705334400; // Jan 15, 2024
  source: 'manual';        // Always user-controlled
}

If you have USD → EUR but need EUR → USD, we automatically compute the inverse (1/rate). The UI marks these as inverse rates so you always know the source.

Blocking Cross-Currency Transfers

One key decision: transfers between different currencies are blocked. This might seem limiting, but it's intentional:

• Which amount is authoritative? If you transfer $100 and receive €85, which side is truth?
• What rate to use? The rate you entered? The rate at transaction time? Something else?
• Hidden fees vanish: Most currency exchanges include fees. A single "transfer" would hide this.

Instead, model currency exchanges as two transactions: an expense from your USD account and an income to your EUR account. This makes the exchange visible and honest.

// Cross-currency "transfer" as two transactions
createTransaction({
  accountId: usdAccount,
  amount: -10000,          // -$100 expense (to exchange)
  payee: 'Currency Exchange'
});

createTransaction({
  accountId: eurAccount,
  amount: 8500,            // +€85 income (from exchange)
  payee: 'Currency Exchange'
});

Currency-Scoped Budgets

Budgets now have a currency field. A USD grocery budget only counts USD grocery transactions. EUR spending doesn't affect your USD budget at all.

This is the honest approach. Mixing currencies in budget tracking would require conversion, which would introduce rate variability into what should be a straightforward comparison.

// Budget calculation filters by currency
async getCategorySpending(
  categoryId: string,
  currency: string,      // Only count this currency
  periodStart: number,
  periodEnd: number
) {
  // Sum only transactions in matching currency
  const transactions = await getTransactions({
    categoryId,
    accountCurrency: currency,
    dateRange: [periodStart, periodEnd]
  });
  return sum(transactions.map(t => t.amount));
}

View-Layer Conversion

When you want to see totals in a single currency, the QueryEngine can execute views with conversion:

// Request conversion in view execution
const result = await queryEngine.executeWithConversion(
  view,
  'EUR',        // Target currency for totals
  Date.now()    // As-of date for rate lookup
);

// Result includes conversion context
result.conversionContext = {
  targetCurrency: 'EUR',
  asOf: 1705334400000,
  conversions: {
    'USD': { rate: 0.85, isInverse: false }
  }
}

The conversion context travels with the data so the UI can show exactly what rate was used and when.

Undo Without Side Effects

Exchange rate changes are fully undoable:

• exchangeRate.create → exchangeRate.revert
• exchangeRate.update → exchangeRate.revert.update
• exchangeRate.delete → exchangeRate.restore

Critically: undoing an exchange rate never mutates transactions. Views simply reflect the new rate availability. This maintains the clean separation between truth (ledger) and view (conversions).

The CurrencyAmount Component

We added a UI component that enforces our transparency principle:

<!-- Always shows currency code, never hides -->
<CurrencyAmount
  amount={10000}
  currency="USD"
  conversion={{ convertedAmount: 8500, ... }}
  showConversionDetails={true}
/>

<!-- Renders: 100.00 USD = 85.00 EUR (rate: 0.8500) -->

The component never hides the currency. It never shows just "$100" when it means "$100 USD = €85 EUR." Transparency is baked into the design.

What We Built

The Principle

This is local-first multi-currency: offline capable, user controlled, fully transparent, and never silently converting your money into something it isn't.

Sprint 17 Checklist

// Sprint 17 Verification
✓ Currency primitive exists (ISO 4217)
✓ Exchange rate primitive with effective dates
✓ No automatic FX fetching
✓ User-provided rates only
✓ LedgerService never converts
✓ Conversion happens in QueryEngine/View only
✓ Cross-currency transfers blocked
✓ Budgets are currency-scoped
✓ Undo works for exchange rate operations
✓ CurrencyAmount component shows transparency
✓ Regression suite passes
✓ MULTI_CURRENCY.md documentation exists
✓ Day 17 Dev Journal is present

════════════════════════════════════════════════════════════
All checklist items complete
════════════════════════════════════════════════════════════