Laravel-Docker-Dev-Template/src/app/Modules/README.md

Module System

🤖 AI Agents: For EXACT file templates, see CLAUDE.md

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

Creating a New Module

# 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

# 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:

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:

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

Use in Controller:

$this->authorize('stock_management.view');

Audit Configuration

Edit Config/module_name.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