# TANRAIL ONE — Core Sales Architecture

## 1. Objective
Provide a unified, business-agnostic transaction engine capable of handling orders, pricing, and payments for any TANRAIL ONE extension (Restaurant, Catering, Water Distribution, Transport).

## 2. Core Concepts
- **Customer**: Exists at the `Organization` level. Can interact with multiple Business Units.
- **Item**: Exists at the `BusinessUnit` level.
- **Order**: Represents a transaction. Tied explicitly to a `Branch` (and thereby a `BusinessUnit`).
- **Payment**: Represents received funds against an Order.

## 3. Order Isolation & Boundary
The invariant `ORDER BU = ORDER BRANCH BU = ORDER LINE ITEM BU` is absolutely strictly enforced. 
A Customer (Org level) can place an order at a Branch (BU A). All items added to that Order MUST belong to BU A. The transaction is financially ring-fenced to BU A.

## 4. Relationship with Inventory
The Sales Core relies completely on the `InventoryService` for physical asset tracking.
- Sales does **not** directly write to `StockBalance` or `StockMovement`.
- When an Order is `CONFIRMED` or `FULFILLED`, the Sales module dispatches an event or explicitly invokes `InventoryService::issue()`.
- If `InventoryService` throws an Exception (e.g., negative stock), the Order confirmation is rejected and rolled back.

## 5. Pricing & Tax Immutability
- `OrderLine` explicitly stores `unit_price`, `quantity`, `tax_amount`, and `total`.
- The price and tax are "frozen" at the moment the item is added to the order.
- Future changes to the `Item` base price or `TaxCategory` rate will **not** affect historical or currently open Orders, ensuring audit compliance.

## 6. Business Extension Layering
The Core Sales engine only knows about Items and Orders. 
- A Restaurant module will map a `Table` to an `Order`.
- A Catering module will map an `Event` to an `Order`.
- The Core does not know what a Table or Event is. It only processes the generic financial transaction.