# TANRAIL ONE — Technical Architecture

## 1. Current State Assessment
Based on an initial inspection of the target repository (`c:\wamp64\www\7`), the directory currently contains a random assortment of Vite/Node.js configurations, CSV/Excel data dumps, and utility scripts (`.cjs` files). 
- **Laravel Framework:** Not present.
- **PHP Setup:** Not present.
- **Conclusion:** The repository is currently serving as a data preparation/scratchpad area. A clean installation of the target architecture is required.

## 2. Target Technology Stack
- **Backend Framework:** Laravel (Latest Stable - PHP 8.2+)
- **Database:** PostgreSQL (Preferred) or MySQL 8.0+
- **Authentication:** TBD (Evaluate Sanctum vs Passport based on future mobile app needs)
- **Frontend Framework:** TBD (Evaluate React/API vs Vue/Inertia based on team skills and mobile requirements)
- **CSS Framework:** TailwindCSS
- **Job Queues:** Redis
- **Storage:** Local (development) / AWS S3 (production)

## 3. Application Layers & Domain Boundaries
TANRAIL ONE will utilize a **Modular Monolith** architecture (e.g., using `nWidart/laravel-modules` or a domain-driven structure).

### Directory Structure Concept:
```text
app/
├── Domains/
│   ├── Core/
│   │   ├── Auth/
│   │   ├── Organization/
│   │   └── Finance/
│   ├── Modules/
│   │   ├── Inventory/
│   │   ├── Sales/
│   │   └── Production/
│   └── Extensions/
│       ├── Restaurant/
│       └── Catering/
```

## 4. Design Patterns & Constraints

### 4.1 Models & Global Scopes
All models representing BU-specific data must implement a `BelongsToBusinessUnit` trait. This trait applies a Global Scope ensuring that `where('business_unit_id', session('active_bu_id'))` is automatically appended to queries.

### 4.2 Services & Actions
Business logic MUST NOT reside in Controllers.
- Use **Action Classes** (e.g., `CreateOrderAction`, `ProcessPaymentAction`) for single-responsibility, highly testable logic.
- Actions ensure that the same order processing logic is used regardless of whether the request comes from the Web UI, an API, or a Console command.

### 4.3 Policies & Authorization
Laravel Policies must be strictly enforced.
- A Policy must first check the User's Active Context.
- Example: `update(User $user, Order $order)` must return `false` if the `$order->business_unit_id` does not match the user's active/permitted BU context.

### 4.4 Events & Observers
Use Events for side-effects.
- Example: When an `OrderPaid` event fires, listeners in the Inventory module reduce stock, and listeners in the Finance module generate a Receipt. This prevents the Sales module from hard-coupling to the Inventory module.

## 5. API Strategy
- The system must expose a clean REST API.
- Future expansions (like a dedicated Kitchen Display iPad App or Driver Mobile App) will consume this API.
- All API routes handling business data must require a `X-Business-Unit-ID` header to establish context.

## 6. Infrastructure (Conceptual)
- **Web Server:** Nginx
- **App Server:** PHP-FPM
- **Workers:** Laravel Horizon (Redis) for background tasks (email, heavy reports, stock reconciliation).
- **Scheduler:** Cron triggering Laravel Scheduler.