# ERPFlow — All Module Commands

Complete reference for every module-related Artisan command in ERPFlow.

All commands run inside the backend container unless noted otherwise:

```bash
docker compose exec backend php artisan <command>
```

---

## Command Index

| # | Command | Category |
|---|---------|----------|
| 1 | [`make:module`](#1-makemodule) | Scaffold |
| 2 | [`delete:module`](#2-deletemodule) | Lifecycle |
| 3 | [`platform:sync`](#3-platformsync) | Lifecycle |
| 4 | [`module:migrate`](#4-modulemigrate) | Lifecycle |
| 5 | [`make:module:model`](#5-mmakemodulemodel) | Artifact Generator |
| 6 | [`make:module:controller`](#6-mmakemodulecontroller) | Artifact Generator |
| 7 | [`make:module:service`](#7-mmakemoduleservice) | Artifact Generator |
| 8 | [`make:module:repository`](#8-mmakemodulerepository) | Artifact Generator |
| 9 | [`make:module:migration`](#9-mmakemodulemigration) | Artifact Generator |
| 10 | [`make:module:seeder`](#10-mmakemoduleseeder) | Artifact Generator |
| 11 | [`make:module:request`](#11-mmakemodulerequest) | Artifact Generator |
| 12 | [`make:module:resource`](#12-mmakemoduleresource) | Artifact Generator |

---

## 1. `make:module`

Scaffold a new ERPFlow module/plugin (backend + frontend).

### Signature

```bash
php artisan make:module {name} [--slug=] [--sync] [--migrate] [--force]
```

### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `name` | Yes | Display/class name (e.g. `HRMS`, `Employee`) |

### Options

| Option | Description |
|--------|-------------|
| `--slug=hrms` | Module slug (defaults from `name` as kebab-case) |
| `--sync` | Run `platform:sync` after scaffold |
| `--migrate` | Run `module:migrate {slug}` after scaffold |
| `--force` | Overwrite existing backend module folder |

### Examples

```bash
docker compose exec backend php artisan make:module HRMS --slug=hrms
docker compose exec backend php artisan make:module Employee --slug=employee --sync --migrate
docker compose exec backend php artisan make:module HRMS --slug=hrms --force
```

### Backend Output (`slug: hrms` → `Modules/Hrms`)

```text
backend/Modules/Hrms/
├── module.json
├── routes/api.php
├── app/
│   ├── Models/
│   ├── Http/Controllers/
│   ├── Http/Requests/
│   ├── Http/Resources/
│   ├── Repositories/
│   └── Services/
└── database/
    ├── migrations/
    └── seeds/
```

### Frontend Output

```text
frontend/src/modules/hrms/
├── index.tsx                    # React routes (landing page wired)
├── pages/HrmsHomePage.tsx       # Landing page
└── api/.gitkeep
```

Also auto-updates:

```text
frontend/src/app/registerModules.ts   # import + register added
```

### `module.json` includes

- `route_prefix`, `api_prefix`
- default menus, permissions, actions
- `frontend_routes` metadata

### After running

```bash
docker compose exec backend php artisan platform:sync
docker compose up -d --build frontend
```

---

## 2. `delete:module`

Delete a module from database and/or filesystem.

### Signature

```bash
php artisan delete:module {slug} [--skip-db] [--skip-files] [--force]
```

### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `slug` | Yes | Module slug or directory name (e.g. `employee`, `Employee`) |

### Options

| Option | Description |
|--------|-------------|
| `--skip-db` | Delete files only; keep DB records |
| `--skip-files` | Delete DB records only; keep files |
| `--force` | Skip confirmation prompt |

### What gets deleted (default)

| Target | Deleted |
|--------|---------|
| Module DB record | Yes |
| Menus / permissions (via FK cascade) | Yes |
| `backend/Modules/{Name}/` | Yes |
| `frontend/src/modules/{slug}/` | Yes |
| `registerModules.ts` entry | Yes |
| Migration tables | No (not rolled back) |

### Behavior notes

- If module is **not in DB**, command auto-falls back to filesystem cleanup.
- Accepts slug (`employee`) or Studly directory name (`Employee`).
- Protected modules (`core`, `auth`, `platform`) cannot be unregistered from frontend.

### Examples

```bash
# Full delete
docker compose exec backend php artisan delete:module employee --force

# Files only (no DB lookup required)
docker compose exec backend php artisan delete:module Employee --skip-db --force

# DB only
docker compose exec backend php artisan delete:module employee --skip-files --force
```

### After running

```bash
docker compose up -d --build frontend
```

---

## 3. `platform:sync`

Discover filesystem plugins and sync metadata to the database.

### Signature

```bash
php artisan platform:sync
```

### What it does

- Scans `backend/Modules/*/module.json`
- Creates/updates module records in DB
- Syncs menus, permissions, actions, dependencies
- Does **not** run migrations

### Example

```bash
docker compose exec backend php artisan platform:sync
```

### When to run

- After `make:module`
- After editing `module.json`
- After adding a new module folder manually

---

## 4. `module:migrate`

Run migrations for a specific module.

### Signature

```bash
php artisan module:migrate {slug} [--force]
```

### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `slug` | Yes | Module slug (e.g. `hrms`, `employee`) |

### Options

| Option | Description |
|--------|-------------|
| `--force` | Force migration in production |

### Example

```bash
docker compose exec backend php artisan module:migrate hrms --force
docker compose exec backend php artisan module:migrate employee --force
```

### Migration path

```text
backend/Modules/{Name}/database/migrations/
```

---

## 5. `make:module:model`

Generate an Eloquent model inside a module.

### Signature

```bash
php artisan make:module:model {slug} {name} [--force]
```

### Example

```bash
docker compose exec backend php artisan make:module:model hrms Employee
```

### Output

```text
backend/Modules/Hrms/app/Models/Employee.php
```

### Namespace

```text
Modules\Hrms\app\Models\Employee
```

---

## 6. `make:module:controller`

Generate a thin REST API controller with try/catch and standardized responses.

### Signature

```bash
php artisan make:module:controller {slug} {name} [--force]
```

### Example

```bash
docker compose exec backend php artisan make:module:controller hrms EmployeeController
```

### Output

```text
backend/Modules/Hrms/app/Http/Controllers/EmployeeController.php
```

### Generated methods

`index`, `store`, `show`, `update`, `destroy`

### Companion hints

If missing, command prints hints for:

- `make:module:service`
- `make:module:request`
- `make:module:resource`

---

## 7. `make:module:service`

Generate a service class and interface (with DB transactions on writes).

### Signature

```bash
php artisan make:module:service {slug} {name} [--force]
```

### Example

```bash
docker compose exec backend php artisan make:module:service hrms EmployeeService
```

### Output

```text
backend/Modules/Hrms/app/Services/EmployeeService.php
backend/Modules/Hrms/app/Contracts/EmployeeServiceInterface.php
```

### Post-step

Add binding in module service provider:

```php
$this->app->bind(EmployeeServiceInterface::class, EmployeeService::class);
```

---

## 8. `make:module:repository`

Generate a repository class and interface.

### Signature

```bash
php artisan make:module:repository {slug} {name} [--force]
```

### Example

```bash
docker compose exec backend php artisan make:module:repository hrms EmployeeRepository
```

### Output

```text
backend/Modules/Hrms/app/Repositories/EmployeeRepository.php
backend/Modules/Hrms/app/Contracts/EmployeeRepositoryInterface.php
```

### Generated methods

`findById`, `paginate`, `create`, `update`, `delete`

### Post-step

```php
$this->app->bind(EmployeeRepositoryInterface::class, EmployeeRepository::class);
```

---

## 9. `make:module:migration`

Generate a migration inside the module migrations folder.

### Signature

```bash
php artisan make:module:migration {slug} {name} [--force]
```

### Example

```bash
docker compose exec backend php artisan make:module:migration hrms create_employees_table
```

### Output

```text
backend/Modules/Hrms/database/migrations/{timestamp}_create_employees_table.php
```

### Apply migration

```bash
docker compose exec backend php artisan module:migrate hrms --force
```

---

## 10. `make:module:seeder`

Generate a seeder class inside the module.

### Signature

```bash
php artisan make:module:seeder {slug} {name} [--force]
```

### Example

```bash
docker compose exec backend php artisan make:module:seeder hrms EmployeeSeeder
```

### Output

```text
backend/Modules/Hrms/database/seeds/EmployeeSeeder.php
```

### Namespace

```text
Modules\Hrms\database\seeds\EmployeeSeeder
```

---

## 11. `make:module:request`

Generate a Form Request for validation.

### Signature

```bash
php artisan make:module:request {slug} {name} [--force]
```

### Example

```bash
docker compose exec backend php artisan make:module:request hrms StoreEmployeeRequest
docker compose exec backend php artisan make:module:request hrms UpdateEmployeeRequest
```

### Output

```text
backend/Modules/Hrms/app/Http/Requests/StoreEmployeeRequest.php
```

---

## 12. `make:module:resource`

Generate an API Resource for response formatting.

### Signature

```bash
php artisan make:module:resource {slug} {name} [--force]
```

### Example

```bash
docker compose exec backend php artisan make:module:resource hrms EmployeeResource
```

### Output

```text
backend/Modules/Hrms/app/Http/Resources/EmployeeResource.php
```

---

## Shared Generator Options

All `make:module:*` artifact generators support:

| Option | Description |
|--------|-------------|
| `--force` | Overwrite existing file |

### Module resolution rules

- Slug `hrms` → directory `backend/Modules/Hrms`
- Slug `system-configuration` → directory `backend/Modules/SystemConfiguration`
- Module folder + `module.json` must exist
- Error if missing: **Run `make:module` first**

### Generated paths summary (`slug: hrms`)

| Generator | Path |
|-----------|------|
| model | `app/Models/{Name}.php` |
| controller | `app/Http/Controllers/{Name}.php` |
| service | `app/Services/{Name}.php` |
| service interface | `app/Contracts/{Name}Interface.php` |
| repository | `app/Repositories/{Name}.php` |
| repository interface | `app/Contracts/{Name}Interface.php` |
| request | `app/Http/Requests/{Name}.php` |
| resource | `app/Http/Resources/{Name}.php` |
| migration | `database/migrations/{timestamp}_{name}.php` |
| seeder | `database/seeds/{Name}.php` |

---

## Recommended Full Workflow

### Create new module with Employee domain

```bash
# 1. Scaffold module
docker compose exec backend php artisan make:module HRMS --slug=hrms --force

# 2. Generate backend artifacts
docker compose exec backend php artisan make:module:model hrms Employee
docker compose exec backend php artisan make:module:migration hrms create_employees_table
docker compose exec backend php artisan make:module:repository hrms EmployeeRepository
docker compose exec backend php artisan make:module:service hrms EmployeeService
docker compose exec backend php artisan make:module:request hrms StoreEmployeeRequest
docker compose exec backend php artisan make:module:request hrms UpdateEmployeeRequest
docker compose exec backend php artisan make:module:resource hrms EmployeeResource
docker compose exec backend php artisan make:module:controller hrms EmployeeController
docker compose exec backend php artisan make:module:seeder hrms EmployeeSeeder

# 3. Register + migrate
docker compose exec backend php artisan platform:sync
docker compose exec backend php artisan module:migrate hrms --force

# 4. Rebuild frontend (landing page + routes)
docker compose up -d --build frontend

# 5. Plugin Manager → install/enable module
# 6. Assign permissions to roles
```

### Delete module completely

```bash
docker compose exec backend php artisan delete:module hrms --force
docker compose up -d --build frontend
```

---

## Quick Copy-Paste Cheatsheet

```bash
# CREATE
docker compose exec backend php artisan make:module {Name} --slug={slug} --sync --migrate

# ARTIFACTS
docker compose exec backend php artisan make:module:model {slug} {Model}
docker compose exec backend php artisan make:module:migration {slug} create_{table}_table
docker compose exec backend php artisan make:module:repository {slug} {Model}Repository
docker compose exec backend php artisan make:module:service {slug} {Model}Service
docker compose exec backend php artisan make:module:request {slug} Store{Model}Request
docker compose exec backend php artisan make:module:resource {slug} {Model}Resource
docker compose exec backend php artisan make:module:controller {slug} {Model}Controller
docker compose exec backend php artisan make:module:seeder {slug} {Model}Seeder

# SYNC & MIGRATE
docker compose exec backend php artisan platform:sync
docker compose exec backend php artisan module:migrate {slug} --force

# DELETE
docker compose exec backend php artisan delete:module {slug} --force

# FRONTEND REBUILD (after scaffold/delete)
docker compose up -d --build frontend
```

---

## Command Registration

All commands are registered in:

```text
backend/app/Platform/Providers/PlatformServiceProvider.php
```

### Source files

```text
backend/app/Platform/Console/
├── MakeModuleCommand.php
├── DeleteModuleCommand.php
├── ModuleMigrateCommand.php
├── PlatformSyncCommand.php
├── MakeModuleModelCommand.php
├── MakeModuleControllerCommand.php
├── MakeModuleServiceCommand.php
├── MakeModuleRepositoryCommand.php
├── MakeModuleMigrationCommand.php
├── MakeModuleSeederCommand.php
├── MakeModuleRequestCommand.php
├── MakeModuleResourceCommand.php
└── Concerns/
    ├── ResolvesModulePaths.php
    └── ManagesFrontendModuleScaffold.php
```

---

*ERPFlow custom plugin architecture — no nwidart/laravel-modules.*