<laravel-boost-guidelines>
=== foundation rules ===

# Laravel Boost Guidelines

The Laravel Boost guidelines are specifically curated by Laravel maintainers for this application. These guidelines should be followed closely to enhance the user's satisfaction building Laravel applications.

## Foundational Context
This application is a Laravel application and its main Laravel ecosystems package & versions are below. You are an expert with them all. Ensure you abide by these specific packages & versions.

- php - 8.3.17
- laravel/framework (LARAVEL) - v10
- laravel/prompts (PROMPTS) - v0
- livewire/livewire (LIVEWIRE) - v3
- laravel/pint (PINT) - v1
- alpinejs (ALPINEJS) - v3
- laravel-echo (ECHO) - v1
- tailwindcss (TAILWINDCSS) - v3


## Conventions
- You must follow all existing code conventions used in this application. When creating or editing a file, check sibling files for the correct structure, approach, naming.
- Use descriptive names for variables and methods. For example, `isRegisteredForDiscounts`, not `discount()`.
- Check for existing components to reuse before writing a new one.

## Verification Scripts
- Do not create verification scripts or tinker when tests cover that functionality and prove it works. Unit and feature tests are more important.

## Application Structure & Architecture
- Stick to existing directory structure - don't create new base folders without approval.
- Do not change the application's dependencies without approval.

## Frontend Bundling
- If the user doesn't see a frontend change reflected in the UI, it could mean they need to run `npm run build`, `npm run dev`, or `composer run dev`. Ask them.

## Replies
- Be concise in your explanations - focus on what's important rather than explaining obvious details.

## Documentation Files
- You must only create documentation files if explicitly requested by the user.


=== boost rules ===

## Laravel Boost
- Laravel Boost is an MCP server that comes with powerful tools designed specifically for this application. Use them.

## Artisan
- Use the `list-artisan-commands` tool when you need to call an Artisan command to double check the available parameters.

## URLs
- Whenever you share a project URL with the user you should use the `get-absolute-url` tool to ensure you're using the correct scheme, domain / IP, and port.

## Tinker / Debugging
- You should use the `tinker` tool when you need to execute PHP to debug code or query Eloquent models directly.
- Use the `database-query` tool when you only need to read from the database.

## Reading Browser Logs With the `browser-logs` Tool
- You can read browser logs, errors, and exceptions using the `browser-logs` tool from Boost.
- Only recent browser logs will be useful - ignore old logs.

## Searching Documentation (Critically Important)
- Boost comes with a powerful `search-docs` tool you should use before any other approaches. This tool automatically passes a list of installed packages and their versions to the remote Boost API, so it returns only version-specific documentation specific for the user's circumstance. You should pass an array of packages to filter on if you know you need docs for particular packages.
- The 'search-docs' tool is perfect for all Laravel related packages, including Laravel, Inertia, Livewire, Filament, Tailwind, Pest, Nova, Nightwatch, etc.
- You must use this tool to search for Laravel-ecosystem documentation before falling back to other approaches.
- Search the documentation before making code changes to ensure we are taking the correct approach.
- Use multiple, broad, simple, topic based queries to start. For example: `['rate limiting', 'routing rate limiting', 'routing']`.
- Do not add package names to queries, package information is already shared. Use `test resource table`, not `filament 4 test resource table`.

### Available Search Syntax
- You can and should pass multiple queries at once. The most relevant results will be returned first.

1. Simple Word Searches with auto-stemming - query=authentication - finds 'authenticate' and 'auth'
2. Multiple Words (AND Logic) - query=rate limit - finds knowledge containing both "rate" AND "limit"
3. Quoted Phrases (Exact Position) - query="infinite scroll" - Words must be adjacent and in that order
4. Mixed Queries - query=middleware "rate limit" - "middleware" AND exact phrase "rate limit"
5. Multiple Queries - queries=["authentication", "middleware"] - ANY of these terms


=== laravel/core rules ===

## Do Things the Laravel Way

- Use `php artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using the `list-artisan-commands` tool.
- If you're creating a generic PHP class, use `artisan make:class`.
- Pass `--no-interaction` to all Artisan commands to ensure they work without user input. You should also pass the correct `--options` to ensure correct behavior.

### Database
- Always use proper Eloquent relationship methods with return type hints. Prefer relationship methods over raw queries or manual joins.
- Use Eloquent models and relationships before suggesting raw database queries
- Avoid `DB::`; prefer `Model::query()`. Generate code that leverages Laravel's ORM capabilities rather than bypassing them.
- Generate code that prevents N+1 query problems by using eager loading.
- Use Laravel's query builder for very complex database operations.

### Model Creation
- When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `list-artisan-commands` to check the available options to `php artisan make:model`.

### APIs & Eloquent Resources
- For APIs, default to using Eloquent API Resources and API versioning unless existing API routes do not, then you should follow existing application convention.

### Controllers & Validation
- Always create Form Request classes for validation rather than inline validation in controllers. Include both validation rules and custom error messages.
- Check sibling Form Requests to see if the application uses array or string based validation rules.

### Queues
- Use queued jobs for time-consuming operations with the `ShouldQueue` interface.

### Authentication & Authorization
- Use Laravel's built-in authentication and authorization features (gates, policies, Sanctum, etc.).

### URL Generation
- When generating links to other pages, prefer named routes and the `route()` function.

### Configuration
- Use environment variables only in configuration files - never use the `env()` function directly outside of config files. Always use `config('app.name')`, not `env('APP_NAME')`.

### Testing
- When creating models for tests, use the factories for the models. Check if the factory has custom states that can be used before manually setting up the model.
- Faker: Use methods such as `$this->faker->word()` or `fake()->randomDigit()`. Follow existing conventions whether to use `$this->faker` or `fake()`.
- When creating tests, make use of `php artisan make:test [options] <name>` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests.

### Vite Error
- If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `npm run build` or ask the user to run `npm run dev` or `composer run dev`.


=== laravel/v10 rules ===

## Laravel 10

- Use the `search-docs` tool to get version specific documentation.
- Middleware typically live in `app/Http/Middleware/` and service providers in `app/Providers/`.
- There is no `bootstrap/app.php` application configuration in Laravel 10:
    - Middleware registration is in `app/Http/Kernel.php`
    - Exception handling is in `app/Exceptions/Handler.php`
    - Console commands and schedule registration is in `app/Console/Kernel.php`
    - Rate limits likely exist in `RouteServiceProvider` or `app/Http/Kernel.php`
- When using Eloquent model casts, you must use `protected $casts = [];` and not the `casts()` method. The `casts()` method isn't available on models in Laravel 10.


=== livewire/core rules ===

## Livewire Core
- Use the `search-docs` tool to find exact version specific documentation for how to write Livewire & Livewire tests.
- Use the `php artisan make:livewire [Posts\\CreatePost]` artisan command to create new components
- State should live on the server, with the UI reflecting it.
- All Livewire requests hit the Laravel backend, they're like regular HTTP requests. Always validate form data, and run authorization checks in Livewire actions.

## Livewire Best Practices
- Livewire components require a single root element.
- Use `wire:loading` and `wire:dirty` for delightful loading states.
- Add `wire:key` in loops:

    ```blade
    @foreach ($items as $item)
        <div wire:key="item-{{ $item->id }}">
            {{ $item->name }}
        </div>
    @endforeach
    ```

- Prefer lifecycle hooks like `mount()`, `updatedFoo()`) for initialization and reactive side effects:

<code-snippet name="Lifecycle hook examples" lang="php">
    public function mount(User $user) { $this->user = $user; }
    public function updatedSearch() { $this->resetPage(); }
</code-snippet>


## Testing Livewire

<code-snippet name="Example Livewire component test" lang="php">
    Livewire::test(Counter::class)
        ->assertSet('count', 0)
        ->call('increment')
        ->assertSet('count', 1)
        ->assertSee(1)
        ->assertStatus(200);
</code-snippet>


    <code-snippet name="Testing a Livewire component exists within a page" lang="php">
        $this->get('/posts/create')
        ->assertSeeLivewire(CreatePost::class);
    </code-snippet>


=== livewire/v3 rules ===

## Livewire 3

### Key Changes From Livewire 2
- These things changed in Livewire 2, but may not have been updated in this application. Verify this application's setup to ensure you conform with application conventions.
    - Use `wire:model.live` for real-time updates, `wire:model` is now deferred by default.
    - Components now use the `App\Livewire` namespace (not `App\Http\Livewire`).
    - Use `$this->dispatch()` to dispatch events (not `emit` or `dispatchBrowserEvent`).
    - Use the `components.layouts.app` view as the typical layout path (not `layouts.app`).

### New Directives
- `wire:show`, `wire:transition`, `wire:cloak`, `wire:offline`, `wire:target` are available for use. Use the documentation to find usage examples.

### Alpine
- Alpine is now included with Livewire, don't manually include Alpine.js.
- Plugins included with Alpine: persist, intersect, collapse, and focus.

### Lifecycle Hooks
- You can listen for `livewire:init` to hook into Livewire initialization, and `fail.status === 419` for the page expiring:

<code-snippet name="livewire:load example" lang="js">
document.addEventListener('livewire:init', function () {
    Livewire.hook('request', ({ fail }) => {
        if (fail && fail.status === 419) {
            alert('Your session expired');
        }
    });

    Livewire.hook('message.failed', (message, component) => {
        console.error(message);
    });
});
</code-snippet>


=== pint/core rules ===

## Laravel Pint Code Formatter

- You must run `vendor/bin/pint --dirty` before finalizing changes to ensure your code matches the project's expected style.
- Do not run `vendor/bin/pint --test`, simply run `vendor/bin/pint` to fix any formatting issues.


=== tailwindcss/core rules ===

## Tailwind Core

- Use Tailwind CSS classes to style HTML, check and use existing tailwind conventions within the project before writing your own.
- Offer to extract repeated patterns into components that match the project's conventions (i.e. Blade, JSX, Vue, etc..)
- Think through class placement, order, priority, and defaults - remove redundant classes, add classes to parent or child carefully to limit repetition, group elements logically
- You can use the `search-docs` tool to get exact examples from the official documentation when needed.

### Spacing
- When listing items, use gap utilities for spacing, don't use margins.

    <code-snippet name="Valid Flex Gap Spacing Example" lang="html">
        <div class="flex gap-8">
            <div>Superior</div>
            <div>Michigan</div>
            <div>Erie</div>
        </div>
    </code-snippet>


### Dark Mode
- If existing pages and components support dark mode, new pages and components must support dark mode in a similar way, typically using `dark:`.


=== tailwindcss/v3 rules ===

## Tailwind 3

- Always use Tailwind CSS v3 - verify you're using only classes supported by this version.


=== tests rules ===

## Test Enforcement

- Every change must be programmatically tested. Write a new test or update an existing test, then run the affected tests to make sure they pass.
- Run the minimum number of tests needed to ensure code quality and speed. Use `php artisan test` with a specific filename or filter.


=== .ai/new_model rules ===

## Creating new modules

### 1. Project structure
This project is a Laravel 10 project and we are using akaunting/laravel-module to manage modules.
Each module is a separate folder in the `modules` folder, and acts as a separate Laravel application.

### 2. Creating a new module
php artisan module:make <module-name>
php artisan module:make-migration create_<table-name>_table <module-name>
php artisan module:make-model <model-name> <module-name>
php artisan module:make-factory <factory-name> --model=<model-name> <module-name>
php artisan tinker
\Modules\<module-name>\Models\<model-name>::factory()->count(10)->create();

### 3. Structure of a module
Each module follows Laravel conventions with these directories:
- Config/ - Module configuration files
- Console/ - Artisan commands
- Database/
  - Migrations/ - Database migrations
  - Seeds/ - Database seeders
  - Factories/ - Model factories
- Events/ - Event classes
- Http/
  - Controllers/ - HTTP controllers
  - Middleware/ - HTTP middleware
  - Requests/ - Form request classes
- Jobs/ - Queueable jobs
- Listeners/ - Event listeners
- Models/ - Eloquent models
- Notifications/ - Notification classes
- Providers/ - Service providers (Main.php is the main provider)
- Resources/views/ - Blade templates
- Routes/ - Route definitions (api.php, web.php)
- Traits/ - PHP traits
- composer.json - Composer dependencies
- module.json - Module configuration
- package.json - NPM dependencies
- webpack.mix.js - Laravel Mix configuration

### 4. module.json Configuration
The module.json file is the heart of module configuration. Key properties include:

```json
{
    "alias": "modulealias",                    // Unique module identifier
    "version": "1.0",                         // Module version
    "nameSpace": "Modules\\ModuleName",       // PHP namespace
    "description": "",                        // Module description
    "keywords": [],                           // SEO keywords
    "active": 1,                              // Is module active
    "order": 0,                               // Load order
    "providers": [                            // Service providers to register
        "Modules\\ModuleName\\Providers\\Main"
    ],
    "aliases": {},                            // Class aliases
    "files": [],                              // Files to autoload
    "requires": [],                           // Module dependencies
    
    // UI Integration
    "hasSidebar": true,                       // Has sidebar apps
    "hasDashboardInfo": true,                 // Shows on dashboard
    "alwayson": true,                         // Always active
    "beforeMainMenus": true,                  // Menu position
    
    // Sidebar Apps (if hasSidebar is true)
    "sidebarData": [
        {
            "name": "App Name",
            "app": "appkey",
            "icon": "https://example.com/icon.svg",
            "brandColor": "#8966FE",
            "view": "modulealias::chat.sideapp.app",
            "script": "modulealias::chat.sideapp.script"
        }
    ],
    
    // Cost Configuration
    "cost_per_action": [
        {
            "name": "Action Name",
            "action": "action_key",
            "cost": 1,
            "default_cost": 1
        }
    ],
    
    // Configuration Fields
    "global_fields": [                        // System-wide settings
        {
            "separator": "Section Name",
            "title": "Setting Title",
            "key": "SETTING_KEY",
            "help": "Help text",
            "ftype": "input",                 // input, bool, select, textarea
            "value": "default_value",
            "data": {}                        // For select options
        }
    ],
    
    "vendor_fields": [                        // Company-specific settings
        {
            "separator": "Section Name",
            "title": "Setting Title",
            "key": "vendor_setting_key",
            "ftype": "input",
            "icon": "🔗",
            "value": ""
        }
    ],
    
    // Menu Configuration
    "staffmenus": [                           // Menus for staff users
        {
            "name": "Menu Item",
            "icon": "ni ni-icon-name text-color",
            "route": "module.route.name",
            "color": "#2dce89",
            "priority": 1,
            "onlyin": "modulealias",          // Show only in this module
            "isGroup": true,                  // Has submenu
            "menus": []                       // Submenu items
        }
    ],
    
    "ownermenus": [                           // Menus for owner users
        // Same structure as staffmenus
    ],
    
    // Additional configurations
    "actions_cost_config": {
        "action_name": 1
    },
    
    // Feature flags
    "isLinkFetcher": false,                   // Module fetches links
    "hasFlows": false                         // Module has workflow support
}
```

### 5. Service Provider (Main.php)
The main service provider handles:
- Configuration loading
- View registration
- Translation loading
- Route registration
- Migration loading
- View component registration

### 6. Model Guidelines
- Models should extend appropriate base classes
- Use CompanyScope for multi-tenant data isolation
- Define relationships properly
- Use Model::booted() for global scopes
- Example:
```php
namespace Modules\ModuleName\Models;

use Illuminate\Database\Eloquent\Model;
use App\Scopes\CompanyScope;

class ModelName extends Model
{
    protected $table = 'table_name';
    protected $fillable = ['field1', 'field2'];
    
    protected static function booted()
    {
        static::addGlobalScope(new CompanyScope);
    }
    
    public function company()
    {
        return $this->belongsTo(\App\Models\Company::class);
    }
}
```

### 7. Controller Guidelines
- Controllers should extend App\Http\Controllers\Controller
- Use traits for common functionality (e.g., Whatsapp trait)
- Implement proper authorization checks
- Follow RESTful conventions

### 8. Routes
- Define routes in Routes/web.php or Routes/api.php
- Use route names with module prefix: 'modulename.controller.action'
- Group routes with middleware and prefixes

### 9. Views
- Place views in Resources/views/
- Reference views as: 'modulealias::folder.viewname'
- Use Blade templating
- Extend appropriate layouts

### 10. Database Migrations
- Create migrations with: php artisan module:make-migration
- Follow Laravel migration conventions
- Include proper up() and down() methods
- Handle exceptions for existing tables/columns
</laravel-boost-guidelines>