# Folder Structure

This guide explains the standard folder organization for creating a new module in our domain-driven architecture.

## Domain Hierarchy

```
app/Domains/
├── Accounting/           # Financial operations
├── Construction/         # Project and contractor management
├── Core/                 # Shared functionality (Auth, Users, Settings)
├── CRM/                  # Customer relationship management
├── Maintenance/          # Asset and service maintenance
├── Management/           # HR, Payroll, Recruitment
├── Procurement/          # Purchasing and orders
├── Sales/                # Sales operations
└── Supply/               # Supply chain management
```

## Standard Module Structure

When creating a new module, follow this folder structure:

```
app/Domains/{MainDomain}/{SubDomain}/
├── DTOs/                           # Data Transfer Objects
│   └── YourEntityDTO.php
├── Enums/                          # Enum classes (optional)
│   └── YourEntityStatus.php
├── Http/
│   ├── Controllers/
│   │   └── V1/                     # API versioning
│   │       └── YourEntityController.php
│   ├── Requests/
│   │   └── V1/                     # Validation requests
│   │       ├── StoreYourEntityRequest.php
│   │       └── UpdateYourEntityRequest.php
│   └── Resources/                  # API Resources
│       └── YourEntityResource.php
├── Models/                         # Eloquent Models
│   └── YourEntity.php
├── Routes/                         # Route definitions
│   └── api.php
├── Services/                       # Business logic
│   └── YourEntityService.php
├── Repositories/                   # Data access (optional)
│   └── YourEntityRepository.php
├── Contracts/                      # Interfaces (optional)
│   └── YourEntityRepositoryContract.php
├── Listeners/                      # Event listeners (optional)
│   └── YourEntityCreatedListener.php
├── Events/                         # Domain events (optional)
│   └── YourEntityCreated.php
├── Rules/                          # Custom validation rules (optional)
│   └── YourCustomRule.php
└── Traits/                         # Shared traits (optional)
    └── HasYourFeature.php
```

## Creating a New Module

### Step 1: Create the Folder Structure

```bash
# Create main directories
mkdir -p app/Domains/YourDomain/YourModule/DTOs
mkdir -p app/Domains/YourDomain/YourModule/Enums
mkdir -p app/Domains/YourDomain/YourModule/Http/Controllers/V1
mkdir -p app/Domains/YourDomain/YourModule/Http/Requests/V1
mkdir -p app/Domains/YourDomain/YourModule/Http/Resources
mkdir -p app/Domains/YourDomain/YourModule/Models
mkdir -p app/Domains/YourDomain/YourModule/Routes
mkdir -p app/Domains/YourDomain/YourModule/Services
```

### Step 2: Choose Your Domain

Select the appropriate main domain based on functionality:

| Domain | Use For |
|--------|---------|
| `Accounting` | Financial transactions, invoices, accounts |
| `Construction` | Projects, contractors, materials |
| `Core` | Authentication, users, settings, shared features |
| `CRM` | Contacts, leads, interactions |
| `Maintenance` | Assets, service requests, technicians |
| `Management` | HR, payroll, recruitment, attendance |
| `Procurement` | Purchase orders, suppliers, drivers |
| `Sales` | Sales orders, quotations |
| `Supply` | Supply orders, inventory management |

### Step 3: Name Your SubDomain

SubDomain names should be:
- **PascalCase**: `PayrollPipeline`, `Recruitment`
- **Descriptive**: Clearly indicate the feature
- **Singular or Compound**: `Invoice`, `EmployeeRequest`

## Example Structures

### Simple Module (CRUD Only)

```
app/Domains/Management/TaskManagement/
├── DTOs/
│   └── TaskDTO.php
├── Http/
│   ├── Controllers/V1/
│   │   └── TaskController.php
│   ├── Requests/V1/
│   │   └── TaskRequest.php
│   └── Resources/
│       └── TaskResource.php
├── Models/
│   └── Task.php
├── Routes/
│   └── api.php
└── Services/
    └── TaskService.php
```

### Complex Module (With Relationships)

```
app/Domains/Management/PayrollPipeline/
├── DTOs/
│   ├── PayrollRunDTO.php
│   └── SalarySlipDTO.php
├── Enums/
│   ├── PayrollRunStatus.php
│   └── SalarySlipStatus.php
├── Http/
│   ├── Controllers/V1/
│   │   ├── PayrollRunController.php
│   │   └── SalarySlipController.php
│   ├── Requests/V1/
│   │   ├── GeneratePayrollRunRequest.php
│   │   └── UpdateSalarySlipRequest.php
│   └── Resources/
│       ├── PayrollRunResource.php
│       └── SalarySlipResource.php
├── Models/
│   ├── PayrollRun.php
│   └── SalarySlip.php
├── Repositories/
│   └── PayrollRepository.php
├── Routes/
│   └── api.php
└── Services/
    ├── PayrollGenerationService.php
    └── SalarySlipService.php
```

### Module with Events

```
app/Domains/Accounting/InvoiceManagement/
├── DTOs/
│   └── InvoiceDTO.php
├── Events/
│   ├── InvoiceCreated.php
│   └── InvoicePaid.php
├── Listeners/
│   ├── SendInvoiceNotification.php
│   └── UpdateAccountingRecords.php
├── Http/
│   └── ...
├── Models/
│   └── Invoice.php
├── Routes/
│   └── api.php
└── Services/
    └── InvoiceService.php
```

## Namespace Conventions

Follow these namespace patterns:

```php
// Model
namespace App\Domains\Management\TaskManagement\Models;

// DTO
namespace App\Domains\Management\TaskManagement\DTOs;

// Service
namespace App\Domains\Management\TaskManagement\Services;

// Controller
namespace App\Domains\Management\TaskManagement\Http\Controllers\V1;

// Request
namespace App\Domains\Management\TaskManagement\Http\Requests\V1;

// Resource
namespace App\Domains\Management\TaskManagement\Http\Resources;

// Enum
namespace App\Domains\Management\TaskManagement\Enums;
```

## Integration Points

### 1. Route Registration

Add your module routes to the main domain routes file:

**Location:** `routes/apis/{domain}.php`

```php
// In routes/apis/management.php
require base_path('app/Domains/Management/TaskManagement/Routes/api.php');
```

### 2. Database Migration

Create migration in the standard location:

```bash
php artisan make:migration create_tasks_table
```

### 3. Permission Seeder

Add permissions for your module:

```php
// In database/seeders/YourModulePermissionsSeeder.php
```

## Best Practices

### DO:

1. **Keep modules focused** - One primary entity per module
2. **Use consistent naming** - Follow established conventions
3. **Create all required files** - Don't skip DTOs or Resources
4. **Place shared code in Core** - If used by multiple domains

### DON'T:

1. **Don't create deeply nested structures** - Max 2 levels deep
2. **Don't mix domain concerns** - Keep features separate
3. **Don't skip the DTO layer** - Even for simple CRUD
4. **Don't hardcode cross-domain dependencies** - Use events or interfaces

## File Count Reference

A typical module should have:

| Complexity | Files | Description |
|------------|-------|-------------|
| Simple | 6-8 | Basic CRUD operations |
| Medium | 10-15 | Multiple models, relationships |
| Complex | 15-25 | Events, listeners, multiple services |