# TANRAIL ONE — Phase 3 Core Data Model

## 1. Customer Model
Generic and universal. Cannot be tied to "Diners" or "Event Hosts".
- **Attributes:** `id`, `name`, `email`, `phone`, `type` (Individual, Corporate), `status`.
- **Relationships:** Belongs to `Organization` (Global CRM) or `BusinessUnit` (Isolated CRM).
- **Design Decision:** Customers should primarily belong to the `Organization` to allow cross-selling (e.g., a Restaurant regular booking a Catering event).

## 2. Supplier Model
Generic provider of goods or services.
- **Attributes:** `id`, `name`, `contact_details`, `tax_number`, `status`.
- **Relationships:** Belongs to `Organization` (Global procurement allows bulk buying).

## 3. Product / Service Catalog Architecture
Must support physical items, digital items, services, and packages without hardcoding terms like "Meal".
- **Entity:** `Item` (Avoids the physical connotation of "Product").
- **Attributes:** `id`, `business_unit_id` (Catalogs are BU-specific), `sku`, `name`, `description`, `type` (Physical, Service, Package), `track_inventory` (Boolean), `base_price`, `tax_category_id`, `status`.
- **Unit of Measure:** Relates to a `Unit` table (e.g., kg, piece, hour, flat).

## 4. Inventory Architecture
Must track diverse assets (chicken, equipment, water bottles, bus parts).
- **Entity 1:** `StockLocation` (Belongs to a `Branch`. Represents a warehouse, a freezer, or a vehicle).
- **Entity 2:** `StockBalance` (Pivot between `Item` and `StockLocation`). Tracks current quantity and average unit cost.
- **Entity 3:** `StockMovement` (The audit trail). Tracks `item_id`, `from_location_id`, `to_location_id`, `quantity`, `type` (Receive, Transfer, Consume, Adjust), `reference_id` (Polymorphic to Order/Purchase).
- **Design Decision:** Inventory is strictly **Location-scoped**, which rolls up to **Branch**, which rolls up to **Business Unit**.

## 5. Financial Transaction Foundation
Avoids business-specific revenue logic.
- **Order:** The intent to buy. (`id`, `customer_id`, `business_unit_id`, `branch_id`, `status`, `total`).
- **OrderLine:** The items being bought. (`order_id`, `item_id`, `quantity`, `unit_price`, `tax`).
- **Invoice:** The legal request for payment. Relates 1:1 or M:1 to Orders.
- **Payment:** The actual receipt of funds. (`id`, `invoice_id`, `amount`, `method`, `reference`, `date`).
- **Expense:** Internal spending. (`id`, `business_unit_id`, `branch_id`, `amount`, `category`, `description`).

## 6. Payment Architecture
- **Methods:** Cash, Bank Transfer, Mobile Money, Card. Stored as generic ENUMs or a configurable reference table.
- **Reversals:** Never DELETE a payment. Create a negative `Payment` or a specific `Refund` entity linked to the original payment to preserve audit trails.

## 7. Database Conceptual ERD

```text
[Organization]
   │
   ├──< [BusinessUnit] >───< [Branch] >───< [StockLocation]
   │        │                  │
   ├──< [Customer]             ├──< [Order] ────< [OrderLine] >── [Item]
   │        │                  │                    │
   └──< [Supplier]             ├──< [Invoice]       └──< [StockBalance]
            │                  │
            │                  ├──< [Payment]
            │                  │
            └──< [Purchase] <──└──< [Expense]
```

## 8. Database Constraints & Scoping
- **`organization_id`:** Master data (Customers, Suppliers) where sharing makes sense.
- **`business_unit_id`:** Catalog Items, Orders, Invoices, Expenses. This is the primary boundary for financial reporting.
- **`branch_id`:** Stock Locations, physical transactions.
- **Rule:** Do NOT blindly add all three columns to every table. An `Order` belongs to a `Branch`, which inherently belongs to a `BusinessUnit`. Storing `business_unit_id` on the `Order` is a permissible denormalization for query performance (Global Scopes), but must be strictly enforced at the application layer to prevent mismatches.