# README

## Overview

The Primitives module provides foundational reference data that other ERP modules depend on. It includes unit of measure (UoM) definitions for quantity handling and currency definitions for multi-currency financial operations. These are stable, rarely-changing entities that form the measurement and monetary foundation of the system.

This module combines related configuration primitives to simplify dependency management while keeping tax-related functionality separate due to its regulatory complexity.

## Key Features

- **UoM Categories**: Group related units (e.g., Unit, Weight, Volume, Length, Time) with a designated reference unit for each category
- **Unit Definitions**: Define individual units with symbols, names, and conversion factors relative to the reference unit
- **Quantity Conversion**: Convert quantities between any two units within the same category using automatic factor calculation
- **Rounding Precision**: Configure decimal precision per unit to ensure appropriate rounding for business operations
- **Currency Definitions**: Define currencies with ISO 4217 codes, symbols, and decimal precision
- **Base Currency**: Provide the currency catalog that companies reference for base currency assignment (company→currency mapping is owned by the organization module)
- **Exchange Rates**: Maintain date-based exchange rates between currency pairs
- **Amount Conversion**: Convert monetary amounts between currencies using applicable rates

## Module Scope

### In Scope

- UoM category and unit management with conversion factors
- Currency definitions with ISO 4217 codes and symbols
- Exchange rate storage with effective dates
- Quantity conversion between compatible units
- Amount conversion between currencies

### Out of Scope

- Tax configuration and fiscal positions (separate tax-configuration module)
- Product definitions (product-management module)
- Transaction recording (sales, purchase, financial-accounting modules)
- Automatic exchange rate fetching from external APIs

### Scope Decision Rationale

Primitives bundles UoM and currency together because both are **foundational reference data** — stable, rarely-changing definitions that many modules depend on. Combining them in one module simplifies dependency management: downstream modules need only one dependency for measurement and monetary foundations rather than two separate ones.

Tax configuration is excluded despite being "configuration-like" because tax rules are regulatory, jurisdiction-specific, and change frequently. They also require complex logic (tax cascading, fiscal positions) that would bloat a module intended to be simple and stable.

External API integration for exchange rates is excluded to keep this module free of external dependencies and side effects. Rate fetching involves scheduling, error handling, and provider-specific logic that belongs in an integration layer.

## Module Dependencies

- None (this is a foundational module)