Multicurrency Infrastructure -- Feature Spec¶

Status: Implemented in Session 42 Companion steer: ai-steer/multicurrency-steer.md

This is the implementation plan for Tier 1 only (the foundation). Read the steer first -- it covers the problem statement, design principles, three-tier plan, key decisions, risks, and success criteria. Tiers 2 and 3 are outlined at the end of this document but are not detailed.

Overview¶

Tier 1 establishes the currency foundation: budget storage on cases, provider base currency, cost normalization in the matching engine, an exchange rate audit table, and a frontend formatCurrency() utility. No payment models, no tax tables, no gateway integration.

Estimated effort: 3--4 sessions Dependencies: None (builds on existing currency_service.py)

File-by-file change list¶

Database migrations¶

Migration 1: Case budget fields¶

Add two columns to the cases table.

ALTER TABLE cases ADD COLUMN budget_cents INTEGER;
ALTER TABLE cases ADD COLUMN budget_currency VARCHAR(3) DEFAULT 'USD';

• budget_cents: patient's stated budget in smallest currency unit (nullable -- not every patient states a budget)
• budget_currency: ISO 4217 code, defaults to "USD", not nullable once budget_cents is set

Alembic file: alembic/versions/xxxx_add_case_budget_fields.py

Migration 2: Provider base currency¶

Add one column to the providers table.

ALTER TABLE providers ADD COLUMN base_currency VARCHAR(3) DEFAULT 'USD' NOT NULL;

• base_currency: the currency in which the provider bills. Default "USD" for backward compatibility with all 42 existing providers.

Alembic file: alembic/versions/xxxx_add_provider_base_currency.py

Migration 3: Exchange rates table¶

Create the exchange_rates audit table.

CREATE TABLE exchange_rates (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    from_currency VARCHAR(3) NOT NULL,
    to_currency VARCHAR(3) NOT NULL,
    rate DOUBLE PRECISION NOT NULL,
    rate_date DATE NOT NULL,
    source VARCHAR(50) NOT NULL DEFAULT 'frankfurter',
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX ix_exchange_rates_pair_date
    ON exchange_rates (from_currency, to_currency, rate_date);

• rate: stored to 6 decimal places (sufficient for all currency pairs)
• rate_date: the date the rate was published by the source (not created_at)
• source: "frankfurter" for ECB data, "pegged" for fixed-rate currencies, "manual" for overrides

Alembic file: alembic/versions/xxxx_create_exchange_rates_table.py

Migration 4: Procedure costs JSONB schema update¶

No DDL change -- procedure_costs remains a JSONB column on providers. The schema of the JSON content evolves. A data migration script updates existing rows.

Before (current):

{
  "knee_replacement": {
    "min_usd_cents": 600000,
    "max_usd_cents": 1200000
  }
}

After:

{
  "knee_replacement": {
    "min_cents": 600000,
    "max_cents": 1200000,
    "currency": "USD"
  }
}

The legacy keys (min_usd_cents, max_usd_cents) are retained alongside the new keys for backward compatibility during the transition. Once all consumers are updated, the legacy keys are dropped in a follow-up migration.

Alembic file: alembic/versions/xxxx_migrate_procedure_costs_schema.py (data migration, not DDL)

Backend changes¶

app/models/case.py¶

Two new SQLAlchemy mapped columns. No logic changes -- just field definitions.

app/models/provider.py¶

One new field. Existing cost_index and procedure_costs fields remain unchanged.

app/models/exchange_rate.py -- NEW¶

New SQLAlchemy model for the exchange_rates table.

class ExchangeRate(Base, UUIDPrimaryKeyMixin):
    __tablename__ = "exchange_rates"

    from_currency: Mapped[str] = mapped_column(String(3), nullable=False, index=True)
    to_currency: Mapped[str] = mapped_column(String(3), nullable=False, index=True)
    rate: Mapped[float] = mapped_column(Float, nullable=False)
    rate_date: Mapped[date] = mapped_column(Date, nullable=False)
    source: Mapped[str] = mapped_column(String(50), nullable=False, default="frankfurter")
    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())

app/services/currency_service.py¶

Estimated new lines: ~60

app/services/matching_engine.py¶

Estimated modified lines: ~80

Key design note: The matching engine does not import the database session or call persist_rate() directly. It calls currency_service.convert() which returns the rate and rate_date. The match_service (orchestrator) is responsible for persisting audit data.

app/services/match_service.py¶

Estimated modified lines: ~15

app/services/chat_extractor.py¶

Estimated modified lines: ~20

config/prompts/base/chat_extractor_v2.yaml¶

app/agents/case_orchestrator.py¶

Estimated modified lines: ~25

Frontend changes¶

All frontend files are in the curaway-health-navigator repository.

src/utils/formatCurrency.ts -- NEW¶

New utility function using the browser's Intl.NumberFormat API.

/**
 * Format an amount in cents to a locale-appropriate currency string.
 *
 * @param amountCents - Amount in smallest currency unit (cents/paise/fils)
 * @param currencyCode - ISO 4217 currency code (e.g., "USD", "INR", "AED")
 * @param locale - Optional BCP 47 locale (defaults to navigator.language)
 * @returns Formatted string (e.g., "$6,000.00", "Rs 5,00,000.00", "AED 22,038.00")
 */
export function formatCurrency(
  amountCents: number,
  currencyCode: string = "USD",
  locale?: string,
): string {
  const amount = amountCents / 100;
  const resolvedLocale = locale || navigator.language || "en-US";

  return new Intl.NumberFormat(resolvedLocale, {
    style: "currency",
    currency: currencyCode,
    minimumFractionDigits: 0,
    maximumFractionDigits: 0,
  }).format(amount);
}

/**
 * Format a cost range (min--max) in a locale-appropriate currency string.
 */
export function formatCostRange(
  minCents: number,
  maxCents: number,
  currencyCode: string = "USD",
  locale?: string,
): string {
  const min = formatCurrency(minCents, currencyCode, locale);
  const max = formatCurrency(maxCents, currencyCode, locale);
  return `${min} -- ${max}`;
}

src/components/MatchCard.tsx (or equivalent match result component)¶

src/pages/storefront/ProviderProfile.tsx¶

src/pages/ConversationApp.tsx¶

Seed data updates¶

app/seed_data.py (or equivalent)¶

Tier 2 outline: Payment Infrastructure¶

Scope only -- detailed spec will be written separately when Tier 1 is deployed and validated.

New models¶

Payment gateway service¶

• PaymentGateway abstract base class with create_charge(), capture(), refund(), get_status()
• StripeGateway implementation for USD, EUR, GBP
• RazorpayGateway implementation for INR
• Gateway selection via currency -> gateway mapping in config/payment_gateways.yaml
• Webhook handlers for async payment status updates (Stripe webhooks, Razorpay webhooks)

Provider portal¶

• GET /api/v1/providers/{id}/invoices -- list invoices
• GET /api/v1/providers/{id}/invoices/{invoice_id} -- invoice detail
• GET /api/v1/providers/{id}/payouts -- payout history

Financial events¶

All payment lifecycle events written to the events table: payment.initiated, payment.succeeded, payment.failed, payment.refunded, invoice.generated, payout.initiated, payout.settled.

Tier 3 outline: Compliance¶

Scope only -- detailed spec will be written separately.

Tax configuration¶

• tax_config table: country_code, state_code, tax_type (VAT/GST/sales_tax), rate_bps, effective_date, expires_at
• Tax calculation at invoice generation (not at quote time)
• Seeded with: India 18% GST, UK 20% VAT (medical services may be exempt), UAE 5% VAT, Turkey 8-18% KDV, Thailand 7% VAT, Spain 21% IVA, US (state-by-state)

KYC/AML¶

• Integration with identity verification provider (Onfido or similar)
• Risk scoring per transaction (amount, corridor, patient history)
• Enhanced due diligence for transactions above corridor thresholds

Cross-border regulatory¶

• FEMA compliance for India (inward remittance documentation)
• FCA compliance for UK (payment services authorization)
• CBUAE compliance for UAE (payment processing authorization)
• Per-corridor document requirements stored in corridor_compliance config

Reconciliation¶

• Daily reconciliation job comparing gateway records vs internal transactions
• Discrepancy alerting via events table + notification system
• Monthly settlement reports per provider

Test plan¶

Unit tests¶

Integration tests¶

Frontend tests¶

Edge Cases¶

Implementation checklist¶

Tier 1 tasks with model tier tags¶

Summary: 6 Opus tasks (matching engine cost normalization, budget filter, integration, exchange rate audit design), 23 Sonnet tasks (migrations, model fields, seed data, frontend utility, prompt config, unit tests).

References¶