# Exchange Rates

## Overview

Exchange Rates maintain the conversion ratios between currency pairs with effective dates. Each rate record specifies the source currency, target currency, rate value, and the date from which it applies. The system uses these rates to convert monetary amounts for transactions, reporting, and consolidation.

Rates are date-based to support historical accuracy - a transaction from last month uses last month's rate, not today's rate.

## Business Purpose

Multi-currency operations require accurate exchange rate management:

- **Transaction Recording**: Convert foreign currency invoices to base currency at booking time
- **Financial Reporting**: Consolidate subsidiaries using period-end rates
- **Historical Accuracy**: Audit trail requires rates as of transaction date
- **Variance Analysis**: Compare budgeted rates vs actual rates for currency exposure

Exchange rates ensure monetary consistency while maintaining complete audit traceability.

## Process Flow

```mermaid
flowchart TD
    A[Create Exchange Rate] --> B[Set Currency Pair]
    B --> C[Set Rate Value]
    C --> D[Set Effective Date]
    D --> E{Validate Rate}
    E -->|Invalid| F[Return Error]
    E -->|Valid| G[Save Rate]
    G --> H[Rate Available for Date Range]

    I[Convert Amount] --> J[Find Rate for Date]
    J --> K{Rate Found?}
    K -->|No| L[Return Error or Use Fallback]
    K -->|Yes| M[Apply Rate × Amount]
    M --> N[Return Converted Amount]
```

## Scenario Patterns

- **Daily Rate Updates**: Finance team updates rates daily from central bank or market data feed
- **Period-End Rates**: Month-end closing uses official rates for consolidation
- **Historical Lookup**: Generating report for Q1 uses Q1 rates, not current rates
- **Rate Gap Handling**: Transaction on holiday uses most recent prior rate when exact date unavailable
- **Inverse Calculation**: Rate for USD→EUR automatically provides EUR→USD by inversion

## Test Cases

- Creating rate with valid currency pair and positive rate should succeed
- Rate with zero or negative value should fail validation
- Rate effective date in far future should be allowed (forward rates)
- Looking up rate for date should return most recent rate on or before that date
- Looking up rate with no prior rate should return error or configurable fallback
- Same currency conversion (USD→USD) should return rate of 1.0
- Inverse rate calculation should be mathematically correct (1/rate)
- Updating existing rate for same date should replace previous value

## Reference Links

- [European Central Bank Exchange Rates](https://www.ecb.europa.eu/stats/policy_and_exchange_rates/euro_reference_exchange_rates/html/index.en.html)
- [Open Exchange Rates API](https://openexchangerates.org/)