Currencies module (currencies)

The currencies module in src/cluster_erp/modules/currencies/ serves three kinds of finance reference data: currencies, exchange rates, and payment terms. The currency and exchange-rate models live in the platform core, src/cluster_erp/core/currencies.py; this module seeds them, mounts their routes, and declares their screens. Payment terms are the module's own table. Other modules use these records as foreign-key sources in their forms.

At a glance¶

What the module does¶

• Seeds the ISO 4217 currency list and the standard payment terms at every start, without overwriting existing rows (src/cluster_erp/modules/currencies/module.py:31-62).
• Lists, creates, updates, and soft-deletes currencies, and refreshes the list from the bundled ISO data (src/cluster_erp/server/routes/currencies.py:21-98).
• Stores exchange rates per currency pair and date, converts an amount, and imports the daily rates of the Turkish central bank (src/cluster_erp/modules/currencies/exchange_rates/routes.py:29-144).
• Keeps payment terms with a category, net days, and early-payment discount (src/cluster_erp/modules/currencies/payment_terms/models.py:12-62).

Sub-modules¶

The currency router is defined in the server layer and included first under the module router; the whole router depends on the currencies app entitlement (src/cluster_erp/modules/currencies/module.py:64-82). exchange_rates/models.py only re-exports the core model (src/cluster_erp/modules/currencies/exchange_rates/models.py:1-5).

Data model¶

The seeding and the core routes are also described on reference data and core i18n.

Screens and metadata¶

get_metadata gives the module the label Currencies & Payment Terms (Turkish Para Birimleri ve Ödeme Koşulları) and a sidebar group Finance Settings with two sections: a settings view with the tabs currency, exchange_rate, and payment_term, and a Payment Terms list (src/cluster_erp/modules/currencies/module.py:103-151). The web app lists the module in SYSTEM_APP_SETTINGS, so the settings tabs open from Settings, then System Apps; the code comment states that finance reference data has no app of its own (webapp/js/home.js (SYSTEM_APP_SETTINGS)). Payment-term categories are offered as six choices: advance, net, early discount, end of month, installment, and international (src/cluster_erp/modules/currencies/metadata.py:294-299).

Status and actions¶

Records have an is_active flag and no status field (src/cluster_erp/core/currencies.py:88, src/cluster_erp/modules/currencies/payment_terms/models.py:53-57).

Business rules¶

• The currency seed takes a curated list with symbols and translations and adds every other ISO 4217 currency from pycountry; a currency whose numeric code is blank or already used is skipped (src/cluster_erp/core/currencies.py:1811-1852). Existing codes are left unchanged (src/cluster_erp/core/currencies.py:281-309).
• Update from Internet reads the same bundled data and refreshes numeric code, name, symbol, and translations of existing currencies; it makes no network request (src/cluster_erp/core/currencies.py:311-357).
• Conversion between the same currency returns the amount at rate 1. Otherwise it uses the direct rate of the given date, or the newest direct rate when no date is given, as amount x rate / unit; failing that, the matching reverse rate as amount x unit / rate. Results are rounded to six places (src/cluster_erp/core/currencies.py:383-446). When no rate exists, the route answers not found (src/cluster_erp/modules/currencies/exchange_rates/routes.py:66-79).
• quantize in the conversion passes no rounding mode, and a grep for getcontext and setcontext in src/ finds no change to the decimal context, so the default context of Python's decimal module applies.
• Sync TCMB fetches the central bank's daily XML from the URL in the setting tcmb_url, with the timeout tcmb_timeout_seconds. It stores each foreign currency against TRY with buying, selling, and average rate, creating or updating the row of that date (src/cluster_erp/modules/currencies/exchange_rates/routes.py:131-144, src/cluster_erp/core/currencies.py:448-552, src/cluster_erp/config/settings.py:418-420). The fetch runs in a worker thread; a failure is returned as an error count, not raised (src/cluster_erp/core/currencies.py:454-461).
• A manual rate gets the source manual unless another is given; currency codes are stored in upper case (src/cluster_erp/modules/currencies/exchange_rates/schemas.py:16-24, src/cluster_erp/modules/currencies/exchange_rates/services.py:80-93).
• A payment term code must be free among live terms (src/cluster_erp/modules/currencies/payment_terms/services.py:452-455). The seed holds 45 standard terms in six categories (src/cluster_erp/modules/currencies/payment_terms/services.py:32-409, entries with a code key).
• assert_known_currency refuses a code that is not a live, active currency, with CURRENCY_UNKNOWN and HTTP 422 (src/cluster_erp/core/currencies.py:30-49). At this commit it is called by the subscriptions module (grep for assert_known_currency).

Events and queries¶

The module consumes no contract and produces none; register_events is empty (src/cluster_erp/modules/currencies/module.py:84-85). Other modules use its records as foreign-key sources in metadata: 33 ForeignKeySource entries with module="currencies" in 10 files of other modules (grep).

Permissions¶

Privacy, retention, and history¶

The module stores no personal data and has no privacy_handlers.py. Deletion sets deleted_at (src/cluster_erp/core/currencies.py:273-279, src/cluster_erp/modules/currencies/exchange_rates/services.py:109-133). Changes are captured by change history.

Analytics facts¶

This module has no analytics_facts.py.

Settings and reference data¶

See settings reference.

Tests¶

Found by a grep for modules.currencies and core.currencies in tests/ and by file name in web-client/.

Discrepancies¶

Terms introduced¶

Related pages¶

• Modules index
• Reference data and core i18n
• Money and Decimal
• Settings reference
• API reference for this module

Verified against commit 92f8051 on 2026-11-13.