# TANRAIL ONE — Phase 3 Module Boundaries

## 1. Domain Boundaries

To prevent business logic from leaking, every module strictly defines its boundaries.

### 1.1 Core Domain
- **Responsibility:** Universal business truth (Identity, Money, Inventory, Master Data).
- **Owns:** Users, Roles, Customers, Orders, Invoices, Payments, Items, Stock.
- **Consumes:** Nothing.
- **Produces:** Generic Domain Events (`OrderConfirmed`, `PaymentReceived`).
- **Dependencies:** None.
- **Does NOT own:** UI for kitchen screens, logic for delivery routes, booking calendars.

### 1.2 Reusable Capabilities (e.g., Fleet Management)
- **Responsibility:** Managing vehicles and drivers for delivery.
- **Owns:** Vehicles, Drivers, Routes, Maintenance Logs.
- **Consumes:** Core Orders (to know what to deliver).
- **Produces:** `DeliveryDispatched`, `DeliveryCompleted`.
- **Dependencies:** Core.

### 1.3 Business Extensions (e.g., Restaurant)
- **Responsibility:** Managing dine-in execution.
- **Owns:** Tables, Floorplans, KDS Tickets, Waiter Assignments.
- **Consumes:** Core Items (Menu), Core Orders.
- **Produces:** `TableSeated`, `CourseFired`.
- **Dependencies:** Core, Reusable Capabilities.

## 2. Core Dependency Rule
The dependency direction is strictly one-way downward:

```text
BUSINESS EXTENSION ──> REUSABLE MODULE ──> CORE
```
**CRITICAL RULE:** Core code MUST NOT contain any references to Extension models, Extension namespaces, or Extension-specific terminology. 

## 3. API / Service Boundaries
Internal business logic will be exposed via **Service Classes** (e.g., `OrderService`, `PaymentService`, `InventoryService`).
- **Why Services?** They encapsulate transaction boundaries and complex logic away from Controllers, making them easily callable by both HTTP APIs and asynchronous Queue Workers (or AI Agents).
- **Pattern Avoidance:** We will avoid overly complex CQRS/Command Bus patterns initially to maintain development velocity, opting for straightforward, well-typed Service classes.

## 4. UI Architecture
The UI navigation reflects the architecture. The sidebar is dynamically built based on context and loaded extensions.

**Core Navigation (Always available if permitted):**
- Dashboard
- Customers
- Suppliers
- Catalog (Items)
- Sales (Orders, Invoices)
- Finances (Payments, Expenses)
- Inventory

**Extension Navigation (Injected if BU is Restaurant):**
- Floorplan
- Kitchen Display
- POS Interface

## 5. Audit & Reporting Foundation
- **Audit:** A generic polymorphic `audit_logs` table tracking `user_id`, `action`, `auditable_type`, `auditable_id`, `old_values`, `new_values`. Applied via Model Observers to critical entities (Invoices, Payments, Stock).
- **Reporting:** Reports will query Core tables heavily utilizing the `business_unit_id` scope. Executive reports will utilize `withoutGlobalScope()` to aggregate across the Organization.