# Core Architecture: The Core Module Protocol
# ================================================
* **A highly opinionated, encapsulated module structure for Laravel.**
* **Designed to prevent monolithic spaghetti by enforcing strict boundaries.**

## **Philosophy**

1. **Everything is a Module:** If it's a feature, it belongs in `app/Mod/`.
2. **One Boot File:** No complex Provider naming. Every module has a `Boot.php` at its root.
3. **Strict Encapsulation:** Modules should be self-contained.

## **Directory Structure (Per Module)**

```text
app/Mod/{ModuleName}/
├── Boot.php                   # The single ServiceProvider entry point
├── Console/                   # Artisan Commands
├── Controllers/               # HTTP Controllers (Web & API)
├── Database/                  # Migrations, Factories, Seeders
├── Events/                    # Events & Listeners
├── Jobs/                      # Queueable Jobs
├── Mail/                      # Mailables
├── Mcp/                       # MCP Tools & Servers
├── Models/                    # Eloquent Models (Namespace: Mod\{Mod}\Models)
├── Services/                  # Business Logic (The "Brain")
├── Tests/                     # Pest Tests (Feature & Unit)
└── View/                      # The UI Layer (See views.md)
    ├── Modal/                 # Livewire Components (ViewModels)
    │   ├── Admin/             # Admin-facing ViewModels
    │   └── Web/               # Public-facing ViewModels
    ├── Blade/                 # Dumb Blade Templates
    │   ├── admin/             # Admin templates
    │   └── web/               # Public templates
    ├── Components/            # Reusable Blade Components
    └── routes/                # Route definitions
```

## **Component Details**

### **Boot.php**
The entry point. Must extend `Illuminate\Support\ServiceProvider`.
It registers routes, views, migrations, and binds services.
**Namespace:** `Mod\{Name}`
**Class:** `Boot`

### **Models**
All Eloquent models live here.
**Namespace:** `Mod\{Name}\Models`
**Table Name:** `[module_snake_case]_[table_name]` (e.g., `agentic_plans`).

### **View (Modern Flexy)**
See `views.md` for the strict separation of Logic (Modal) and Layout (Blade).

### **Tests**
Tests must exist within the module.
Run via: `php artisan test app/Mod/{Name}/Tests`

## **Best Practices**

1.  **Skinny Controllers:** Controllers only delegate to Services or return View Modals.
2.  **Explicit Boundaries:** Do not query another module's database tables directly using raw SQL. Use Service contracts or Events if modules need to talk.
3.  **Self-Contained:** A module should be able to be extracted into a composer package with minimal effort.


# Core Architecture: The Core View Protocol (Modern Flexy)
# =========================================================
* **A strict architectural guideline for implementing Server-Side MVVM in Laravel.**
* **Part of the Core PHP Framework.**

## **Philosophy**

1. **The Controller is a Traffic Cop:** It accepts input, delegates to the Domain, and selects a View Modal. It never touches HTML or data formatting.
2. **The View Modal is the Interface:** All presentation logic, formatting, state management, and data preparation happen here. This is the "ViewModel" (implemented as Livewire Components).
3. **The Template is Dumb:** The template file (.blade.php) contains ONLY HTML and simple variable interpolation. No complex logic, no database calls, no calculations.

## **Directory Structure**
Inside a Core Module (`app/Mod/{Name}/`):

```text
View/
├── Modal/                 # The View Modals (Livewire Components)
│   ├── Admin/             # (Namespace: Mod\{Mod}\View\Modal\Admin)
│   │   └── {Resource}Manager.php
│   ├── Web/               # (Namespace: Mod\{Mod}\View\Modal\Web)
│   │   └── {Resource}Page.php
│   └── {Resource}Page.php
└── Blade/                 # The Dumb HTML Templates
    ├── admin/             # (View Namespace: {mod}::admin)
    │   └── {resource}-manager.blade.php
    └── web/               # (View Namespace: {mod}::web)
        └── {resource}-page.blade.php
```

## **Implementation Guide**

### **1. The Controller (Optional with Livewire)**

**Role:** Accept request, fetch raw Domain Entity (if needed), return View Modal.
**Constraint:** Must return an instance of a View Modal or render it via Livewire route binding.

```php
// Example: InvoiceController.php
namespace Mod\Billing\Controllers\Web;

use Mod\Billing\View\Modal\InvoicePage;

class InvoiceController
{
    public function show(int $id)
    {
        // Delegate directly to the View Modal
        // Livewire handles the hydration
        return new InvoicePage($id);
    }
}
```

### **2. The View Modal (The "Flexy" Layer)**

**Role:** Prepare data for display. Format currencies, dates, handle conditional UI logic, and manage state.
**Constraint:** Public properties/methods correspond 1:1 with what the template needs.

```php
// Example: InvoicePage.php
namespace Mod\Billing\View\Modal;

use Livewire\Component;
use Mod\Billing\Models\Invoice;

class InvoicePage extends Component
{
    public Invoice $invoice;

    public function mount(Invoice $invoice)
    {
        $this->invoice = $invoice;
    }

    // Logic lives HERE, not in the HTML.
    public function getInvoiceIdProperty(): string
    {
        return '#' . str_pad($this->invoice->id, 6, '0', STR_PAD_LEFT);
    }

    public function getFormattedTotalProperty(): string
    {
        return number_format($this->invoice->total / 100, 2);
    }

    public function getIsOverdueProperty(): bool
    {
        return $this->invoice->due_date->isPast() && !$this->invoice->paid;
    }

    public function render()
    {
        // Points to the dumb template in the module
        // Structure: app/Mod/Billing/View/Blade/invoice-page.blade.php
        return view('billing::invoice-page');
    }
}
```

### **3. The Template (The Dumb Layer)**

**Role:** Layout and structure only.
**Constraint:** No method calls with arguments. No `@php` blocks. No complex `@if` conditions (use boolean getters from the View Modal instead).

```bladehtml
<!-- invoice-page.blade.php -->
<div class="invoice-container">
    <h1>Invoice {{ $this->invoiceId }}</h1>

    <div class="status">
        <!-- Logic is hidden behind the boolean getter -->
        @if($this->isOverdue)
            <span class="badge-danger">Overdue</span>
        @else
            <span class="badge-success">Active</span>
        @endif
    </div>

    <div class="amount">
        Total: ${{ $this->formattedTotal }}
    </div>
</div>
```

## **Enforcement Rules**

1. **No Logic in Blade:** Regex check for logic operators (`&&`, `||`, `>`) inside `{{ }}` tags in .blade.php files.
2. **No Eloquent in Blade:** The template should interact with the View Modal's getters/properties, not the raw Eloquent model relationships.
3. **Strict Typing:** View Modals must strictly type their dependencies.
