# Module System

> **🤖 AI Agents**: For EXACT file templates, see [CLAUDE.md](../../../CLAUDE.md)

This Laravel application uses a modular architecture to organize features into self-contained modules.

## Creating a New Module

```bash
# Basic module (no model)
php artisan make:module ProductCatalog

# With a model + Filament resource
php artisan make:module ProductCatalog --model=Product

# With API routes
php artisan make:module ProductCatalog --model=Product --api

# Without Filament admin
php artisan make:module ProductCatalog --model=Product --no-filament
```

## What Gets Created

### Basic module (`make:module Name`):
```
app/Modules/Name/
├── Config/name.php                    # Module config
├── Database/Migrations/               # Module migrations
├── Database/Seeders/
├── Filament/Resources/                # Admin resources
├── Http/Controllers/NameController.php
├── Http/Middleware/
├── Http/Requests/
├── Models/
├── Policies/
├── Services/
├── Routes/web.php                     # Frontend routes
├── Resources/views/index.blade.php
├── Permissions.php                    # Module permissions
└── NameServiceProvider.php            # Auto-registered
```

### With `--model=Product`:
Adds:
- `Models/Product.php` (with auditing)
- `Database/Migrations/create_products_table.php`
- `Filament/Resources/ProductResource.php` (full CRUD)

### With `--api`:
Adds:
- `Routes/api.php` (Sanctum-protected)

## Module Features

✅ **ServiceProvider** - Auto-registered, loads routes/views/migrations  
✅ **Config** - Module-specific settings with audit configuration  
✅ **Permissions** - Pre-defined CRUD permissions  
✅ **Filament Admin** - Full CRUD resource with navigation group  
✅ **Auditing** - Track all changes via ModuleAuditable trait  
✅ **Tests** - Feature tests with permission checks  

## Example Usage

```bash
# Create a Stock Management module with Product model
php artisan make:module StockManagement --model=Product --api

# Run migrations
php artisan migrate

# Seed permissions
php artisan db:seed --class=RolePermissionSeeder

# Clear caches
php artisan optimize:clear
```

**Access:**
- Frontend: `http://localhost:8080/stock-management`
- Admin: `http://localhost:8080/admin` → Stock Management section
- API: `http://localhost:8080/api/stock-management`

## Permissions

Each module creates these permissions in `Permissions.php`:

```php
return [
    'stock_management.view' => 'View Stock Management',
    'stock_management.create' => 'Create Stock Management records',
    'stock_management.edit' => 'Edit Stock Management records',
    'stock_management.delete' => 'Delete Stock Management records',
];
```

**Permissions are auto-loaded!** When you run `php artisan db:seed --class=RolePermissionSeeder`, 
it scans all `app/Modules/*/Permissions.php` files and registers them automatically.

Use in Blade:
```blade
@can('stock_management.view')
    <a href="{{ route('stock-management.index') }}">Stock</a>
@endcan
```

Use in Controller:
```php
$this->authorize('stock_management.view');
```

## Audit Configuration

Edit `Config/module_name.php`:

```php
'audit' => [
    'enabled' => true,
    'strategy' => 'all',     // 'all', 'include', 'exclude', 'none'
    'include' => [],         // Fields to audit (if strategy='include')
    'exclude' => ['password'], // Fields to exclude
],
```

## Best Practices

1. **Keep modules independent** - Avoid tight coupling between modules
2. **Use Services** - Put business logic in `Services/`, not controllers
3. **Define clear permissions** - One permission per action
4. **Test your modules** - Run `php artisan test` after creating
5. **Use Filament** - Leverage admin panel for quick CRUD