# TANRAIL ONE — Business Unit Architecture

## 1. Overview
The Business Unit (BU) is the central pivot for data scoping and operational logic in TANRAIL ONE. This document outlines how BUs are configured, managed, and isolated.

## 2. Business Unit Model
A Business Unit represents a distinct commercial entity under TANRAIL Investments Limited.

### Attributes:
- `id`: UUID / Primary Key
- `name`: e.g., "TANRAIL Restaurant", "TANRAIL Catering"
- `code`: e.g., `REST`, `CATER`
- `type`: Relates to the required extensions (e.g., `restaurant`, `catering`)
- `status`: Active, Inactive, Setup
- `currency`: Default operating currency
- `timezone`: Local operational timezone

## 3. Branches and Locations
Every BU must have at least one Branch (even if it's just "Headquarters").
- **Branch:** A physical or logical operating center.
- **Location:** A specific area within a Branch (e.g., "Main Kitchen", "Front Store", "Cold Storage").

## 4. User and Role Assignment
Users do not have global permissions by default. Access is defined by a Pivot relationship linking the User, the Role, and the BU/Branch.

**Example Access Matrix:**
- User A is `Manager` in BU: `Restaurant`, Branch: `Main`.
- User A is `Viewer` in BU: `Catering`, Branch: `All`.
- User B is `Accountant` in BU: `All`, Branch: `All`.

## 5. Module & Capability Activation
Not all BUs need all system features. TANRAIL ONE uses a capability toggle system.

### BU Configuration:
```json
{
  "business_unit_id": 1,
  "enabled_modules": [
    "core.inventory",
    "core.sales",
    "reusable.production",
    "reusable.booking",
    "extension.restaurant"
  ]
}
```
When a User logs into the Restaurant BU context, the UI will only render navigation for these activated modules.

## 6. Data Isolation Strategy (Global vs. Local)

### 6.1 Global Data (No BU ID required)
- Users
- System Roles
- Global Currencies

### 6.2 Shared Data (Optional BU ID)
- **Customers / Suppliers:** If `business_unit_id` is NULL, they are a global customer. If set, they belong only to that BU.
- **Products:** A master product (e.g., "Flour") might be global, but its pricing/inventory is BU-specific.

### 6.3 Strictly Scoped Data (BU ID Required)
- Orders
- Invoices
- Payments
- Expenses
- Inventory Transactions

Every strictly scoped database table MUST include:
- `business_unit_id`
- `branch_id`

## 7. Context Switching
- Upon login, a user with multiple BUs will be prompted to select their **Active Context**.
- The Active Context dictates the `business_unit_id` injected into all subsequent queries (via Global Scopes in Laravel) and UI dashboards.
- Executives can select "Global Context" to view consolidated reporting (which bypasses the local BU scope constraint but requires explicit executive permissions).

## 8. Financial Consolidation
Because all BUs share the same Core Finance tables (Invoices, Expenses), the Executive Dashboard can seamlessly perform:
`SELECT SUM(total) FROM invoices WHERE status = 'paid'` (Consolidated)
`SELECT SUM(total) FROM invoices WHERE business_unit_id = 1 AND status = 'paid'` (BU Specific)