# Currency Definitions

## Overview

Currency Definitions establish the monetary units available for use across the ERP system. Each currency record contains the ISO 4217 code, display symbol, name, and decimal precision. The primitives module owns the **currency master data** — the catalog of available currencies, their metadata, and exchange rates.

In a multi-company setup, each company assigns one of these currencies as its **base/functional currency** via the organization module's company record. The primitives module does not own the company→currency mapping; it provides the currency catalog that organization references. There is no global "base currency" concept at the primitives level — base currency assignment is always per company, owned by the organization module.

This feature provides the foundation for all multi-currency operations in sales, purchasing, and accounting.

## Business Purpose

Organizations operating internationally need to:

- Record transactions in the customer's or vendor's preferred currency
- Convert amounts to a consistent base currency for financial reporting
- Display currency symbols and format amounts correctly by locale
- Handle currencies with different decimal precisions (e.g., JPY has 0 decimals, USD has 2)

Currency definitions ensure consistent monetary handling across all business operations.

## Process Flow

```mermaid
flowchart TD
    A[Define Currency] --> B[Add to Currency Catalog]
    B --> C[Currency Active]
    C --> D[Available for Transactions]
    D --> E[Products Can Set Prices]
    D --> F[Orders Can Use Currency]
    D --> G[Exchange Rates Can Reference]
    D --> H[Companies Can Assign as Base Currency]
```

## Scenario Patterns

- **Initial Setup**: Administrator defines common currencies (e.g., USD, EUR, GBP, JPY) in the currency catalog during system initialization. Base currency assignment is performed per company via the organization module
- **Market Expansion**: Business enters new market and adds local currency (e.g., BRL for Brazil expansion)
- **Currency Deactivation**: Obsolete currency (e.g., legacy national currency replaced by EUR) is deactivated to prevent new transactions while preserving historical data
- **Precision Configuration**: Cryptocurrency or precious metal tracking requires higher decimal precision than standard currencies

## Test Cases

- Creating a currency with valid ISO 4217 code should succeed
- Currency codes must be unique (no duplicate USD)
- The primitives module does not designate a global base currency; base currency assignment is per company and owned by the organization module
- A currency that is assigned as base currency by any company cannot be deactivated (enforced via cross-module check with the organization module)
- Currency with active transactions should not be deletable (only deactivatable)
- Decimal places must be non-negative integer (0-4 typical range)

## Reference Links

- [ISO 4217 Currency Codes](https://www.iso.org/iso-4217-currency-codes.html)
- [Unicode CLDR Currency Data](https://cldr.unicode.org/index/downloads)