shell-leaderboard/docs/module-generator.md

# Module Generator (Admin UI)

A visual tool for creating module skeletons through the Filament admin panel.

> **Development Only**: This tool is only available when `APP_ENV=local`.

## Access

Navigate to: **Admin Panel → Development → Module Generator**

URL: `/admin/module-generator`

## Features

- **Visual Form**: Create modules without command line
- **Auto Git Branch**: Optionally creates `module/{name}` branch and commits files
- **Skeleton Only**: Maximum flexibility - creates structure, you add the models
- **Instant Feedback**: Shows generation logs and next steps

## What Gets Created

```
app/Modules/{ModuleName}/
├── Config/{module_name}.php           # Module configuration
├── Database/
│   ├── Migrations/                     # Empty, add your migrations
│   └── Seeders/                        # Empty, add your seeders
├── Filament/Resources/                 # Empty, add Filament resources
├── Http/
│   ├── Controllers/{ModuleName}Controller.php
│   ├── Middleware/                     # Empty
│   └── Requests/                       # Empty
├── Models/                             # Empty, add your models
├── Policies/                           # Empty, add policies
├── Services/                           # Empty, add services
├── Routes/
│   ├── web.php                         # Basic index route
│   └── api.php                         # If API option selected
├── Resources/views/
│   └── index.blade.php                 # Starter view
├── Permissions.php                     # CRUD permissions
├── {ModuleName}ServiceProvider.php     # Auto-registered
└── README.md                           # Module documentation
```

## Form Options

| Field | Description |
|-------|-------------|
| **Module Name** | PascalCase name (e.g., `Accounting`, `Inventory`) |
| **Description** | Brief description for README and config |
| **Create Git Branch** | Auto-create `module/{name}` branch and commit |
| **Include API Routes** | Add `Routes/api.php` with Sanctum auth |

## Git Integration

When "Create Git Branch" is enabled:

1. **Checks** for uncommitted changes (fails if dirty)
2. **Creates** branch `module/{module-name}`
3. **Generates** all module files
4. **Commits** with message `feat: Add {ModuleName} module skeleton`
5. **Shows** push command: `git push -u origin module/{name}`

### Requirements

- Working directory must be clean (no uncommitted changes)
- Git must be installed in the container
- Repository must be initialized

## After Generation

1. **Run migrations** (if you add any):
   ```bash
   php artisan migrate
   ```

2. **Seed permissions**:
   ```bash
   php artisan db:seed --class=RolePermissionSeeder
   ```

3. **Clear caches**:
   ```bash
   php artisan optimize:clear
   ```

4. **Push branch** (if Git was used):
   ```bash
   git push -u origin module/{name}
   ```

## Adding Models

After generating the skeleton, add models manually:

```php
// app/Modules/Accounting/Models/Invoice.php
<?php

namespace App\Modules\Accounting\Models;

use App\Traits\ModuleAuditable;
use Illuminate\Database\Eloquent\Model;
use OwenIt\Auditing\Contracts\Auditable;

class Invoice extends Model implements Auditable
{
    use ModuleAuditable;

    protected $fillable = [
        'number',
        'customer_id',
        'total',
        'status',
    ];
}
```

## Adding Filament Resources

Create admin CRUD in `Filament/Resources/`:

```php
// app/Modules/Accounting/Filament/Resources/InvoiceResource.php
<?php

namespace App\Modules\Accounting\Filament\Resources;

use App\Modules\Accounting\Models\Invoice;
use Filament\Resources\Resource;
// ... standard Filament resource implementation
```

## Comparison: UI vs CLI

| Feature | UI Generator | `make:module` CLI |
|---------|--------------|-------------------|
| Skeleton only | ✅ | ❌ (includes model) |
| Git integration | ✅ Auto-branch | ❌ Manual |
| Model generation | ❌ | ✅ With `--model=` |
| Filament resource | ❌ | ✅ With `--model=` |
| Visual feedback | ✅ | Terminal output |
| Environment | Local only | Any |

**Use UI Generator when**: You need a blank canvas for complex modules with multiple models.

**Use CLI when**: You want a quick single-model module with all files generated.

## Troubleshooting

### "Git working directory has uncommitted changes"

Commit or stash your changes first:
```bash
git add . && git commit -m "WIP"
# or
git stash
```

### Module not showing in admin

Clear caches:
```bash
php artisan optimize:clear
```

### Permissions not working

Re-seed permissions:
```bash
php artisan db:seed --class=RolePermissionSeeder
```