# Project/Module Name

One-sentence summary of what this does and why it exists.

## Quick Start

Minimal example to get from zero to working in < 2 minutes.

## Installation

Prerequisites, dependencies, and setup steps.

## Usage

### Basic Usage
Most common use case with a working code example.

### Advanced Usage
Less common patterns, configuration options.

## API Reference

Key functions/classes with signatures (or link to generated docs).

## Architecture

Brief description of how this is structured and why.
Link to ADRs for significant decisions.

## Configuration

Environment variables, config files, and their options.

## Development

How to set up for development, run tests, and contribute.

## Troubleshooting

Common issues and their solutions.

def transfer_funds(
    source: Account,
    target: Account,
    amount: Decimal,
    currency: str = "USD",
) -> TransferResult:
    """Transfer funds between two accounts.

    Validates sufficient balance, converts currency if needed, and
    executes the transfer atomically. Emits a TransferCompleted event
    on success.

    Args:
        source: The account to debit.
        target: The account to credit.
        amount: Transfer amount. Must be positive.
        currency: ISO 4217 currency code. Defaults to "USD".

    Returns:
        TransferResult containing transaction ID and final balances.

    Raises:
        InsufficientFundsError: If source balance < amount.
        CurrencyConversionError: If conversion rate unavailable.
        AccountFrozenError: If either account is frozen.

    Example:
        >>> result = transfer_funds(checking, savings, Decimal("500"))
        >>> print(result.transaction_id)
        'txn_abc123'

    Note:
        This operation is idempotent — retrying with the same
        idempotency key will return the original result.
    """

/**
 * Transfer funds between two accounts.
 *
 * Validates sufficient balance, converts currency if needed, and
 * executes the transfer atomically.
 *
 * @param source - The account to debit
 * @param target - The account to credit
 * @param amount - Transfer amount (must be positive)
 * @param options - Optional transfer configuration
 * @returns Promise resolving to TransferResult with transaction ID
 * @throws {InsufficientFundsError} If source balance < amount
 * @throws {AccountFrozenError} If either account is frozen
 *
 * @example
 * ```ts
 * const result = await transferFunds(checking, savings, 500);
 * console.log(result.transactionId); // 'txn_abc123'
 * ```
 */

/**
 * @brief Transfer funds between two accounts.
 *
 * Validates sufficient balance, converts currency if needed,
 * and executes the transfer atomically.
 *
 * @param source The account to debit
 * @param target The account to credit
 * @param amount Transfer amount (must be positive)
 * @return TransferResult containing transaction ID
 * @throws InsufficientFundsError if source balance < amount
 *
 * @code
 * auto result = transfer_funds(checking, savings, 500.0);
 * std::cout << result.transaction_id << std::endl;
 * @endcode
 */

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added
- New features that have been added

### Changed
- Changes in existing functionality

### Deprecated
- Features that will be removed in future versions

### Removed
- Features that have been removed

### Fixed
- Bug fixes

### Security
- Vulnerability fixes