---
description: 
globs: 
alwaysApply: true
---

# Laravel Filament Project Architecture Guidelines

## Core Architecture Principles

1. **Service-Oriented Architecture**
   - Services are the pulsing heart of the application containing all business logic
   - Controllers and commands should never interact directly with the database
   - All operations should flow through appropriate service classes
   - Each service should have a clear, single responsibility

2. **Directory Structure**
   - Organize code by domain in the Units directory: `Modules/Units/{Domain}`
   - Subdirectories reflect distinct concepts within the domain
   - Each unit follows Laravel's directory structure
   - Filament-specific classes go in `{Unit}/Filament/` subdirectory

3. **Clean Code Pattern**
   - Follow SOLID principles consistently throughout the codebase
   - Use proper separation of concerns between layers
   - Implement domain-driven design where appropriate
   - Reduce duplicate code through proper abstraction

4. **Type Safety**
   - Use PHP type hints for parameters and return values
   - Always define property types
   - Use union types (e.g., `Type|null`) where appropriate
   - Leverage PHP enums for type-safe constants

## Naming Conventions

### Classes

- Use **CamelCase** for class names
- Service classes must end with `Service` suffix
- Repository classes must end with `Repository` suffix
- Controllers should end with `Controller` suffix
- Model classes should represent the entity name in singular form

### Properties

- Use **snake_case** for property names
- Prefix private and protected properties with underscore `_`
- Always declare property types 

```php
class UserController
{
  public string $user_name;
  private string $_user_object;
  protected string $_model_object;
}
```

### Methods

- Use **camelCase** for method names
- Prefix private and protected methods with underscore `_`
- Always declare return types
- Service action methods must start with `act`

```php
class UserController
{
  public function showDetails(): void
  private function _loadDetails(): array
  protected function _deleteDetails(): bool
}
```

## Class Structure

### Order of Elements

1. Traits
2. Public properties
3. Private properties
4. Protected properties
5. Constructor method
6. Public methods
7. Private methods
8. Protected methods
9. Magic methods

## Service Layer Guidelines

### Service Class Structure

- Extend `BaseService` for common functionality
- Declare dependencies in constructor
- Use dependency injection for collaborating services
- Group related methods together

### Service Method Requirements

- All action methods must start with `act` prefix
- Always return `$this` from action methods for method chaining
- Never return data directly; use success response mechanism
- Follow transaction management pattern for database operations

```php
public function actVerify(string $mobile, string $code): self
{
    DB::beginTransaction();
    try {
        // Operation logic
        DB::commit();
        $this->setSuccessResponse(['data' => $result]);
    } catch (\Exception $e) {
        DB::rollBack();
        $this->addError([], 'Error message');
    }
    return $this;
}
```

### Service Method Usage

```php
$this->_authService->actGetMobileNumber();
if ($this->_authService->hasErrors()) {
    // Handle errors
} else {
    $data = $this->_authService->getSuccessResponse()->getData();
    // Continue processing
}
```

### Service Property Naming

- Follow general property naming rules
- Use descriptive names for dependent services
- Include service type in property name

## Using Enums Instead of Constants

- Create dedicated enum classes for related constants
- Use strongly-typed enums (string/int) based on database requirements
- Place enum classes in appropriate domain directory structure
- Document each enum case with clear comments

```php
enum UserStatusEnum: int
{
    /**
     * User is active
     */
    case ACTIVE = 1;
    
    /**
     * User is inactive
     */
    case INACTIVE = 0;
}
```

## Documentation Standards

### Copyright Header

Every file should begin with this copyright header:

```php
/*
 * Copyright (C) Saman beheshtian, Inc - All Rights Reserved
 * 2025.
 *
 * Author        Saman beheshtian
 * Position      Developer
 * Email         amintado@gmail.com
 * Phone         +989353466620
 * Date          4/8/25, 7:57 PM
 */
```

### Class Documentation

```php
/**
 * Brief description of class
 *
 * Detailed description of class functionality and purpose
 *
 * Error code: [if applicable]
 * Singleton: true|false
 */
```

### Method Documentation

For service action methods:

```php
/**
 * Brief description
 *
 * Detailed description
 *
 * return data:
 * ```
 *  [
 *      'mobile' => 'string',
 *      'name' => 'string'
 *  ]
 * ```
 *
 * @param string $param1 Description
 * @param int $param2 Description
 * @return self
 * @throws \SomeException
 */
```

### Model Property Documentation

```php
/**
 * @property string $name
 * @property string $email
 * @property int $status
 */
```

## Database Interaction

1. **Transaction Management**
   - Wrap related database operations in transactions
   - Use try/catch with appropriate rollback
   - Log database exceptions with context

2. **Model Usage**
   - Use models for all database operations
   - Avoid raw queries except for performance-critical operations
   - Define relationships in the model classes
   - Use proper type casting

3. **Error Handling**
   - Capture specific database exceptions with meaningful messages
   - Provide context in error messages for easier debugging
   - Use addError method with appropriate error codes

4. **Metadata Strategy**
   - For flexible data structures, use metadata tables
   - Implement service methods for metadata operations
   - Ensure proper indexing on metadata tables

## Testing Guidelines

### General Testing Principles

1. Read the code thoroughly before writing tests
2. Understand what's being returned from methods
3. Write assertions for both happy and error paths
4. Use the RefreshDatabase trait for database tests
5. Define test data as class properties
6. Use assertModelExists for database assertions
7. Place all tests in the Modules/FlowTest directory with FlowTest namespace

### Flow Testing Methodology

1. **Test Data Management**
   - Define test data as class properties with `protected array $testData`
   - Initialize dynamic test data in `setUp()`
   - Organize data into logical groups
   - Use factory patterns for model creation

2. **Form Testing**
   - Use `set('data', $formData)` for Filament forms
   - Match form data structure exactly
   - Use dot notation for nested data
   - Test validation rules thoroughly

3. **Flow Testing Structure**
   - Follow user flows precisely
   - Break complex flows into logical steps
   - Add clear comments for each stage
   - Test both positive and negative paths

4. **Error Scenarios**
   - Test validation errors
   - Test business rule violations
   - Test permission restrictions
   - Test edge cases and boundary conditions

## Additional Guidelines

1. **Use Value Objects**
   - Use DTOs for data transfer between layers
   - Implement validation at DTO creation
   - Use static factory methods for DTOs

2. **Implement Security Practices**
   - Validate - Use proper authentication and authorization
   - Sanitize data before display
   - Implement proper access control

3. **Performance Considerations**
   - Use eager loading for related models
   - Optimize database queries
   - Implement caching where appropriate
   - Use pagination for large datasets

4. **Code Consistency**
   - Follow PSR-12 coding standards
   - Use consistent naming conventions
   - Implement proper error handling
   - Document code thoroughly
## Commit message Guidelines
1. Always create new branch and push changes to that
2. Under commit message, echo files affected count
3. then create pull request to merge to main branch
These guidelines ensure code maintainability, reliability, and consistency throughout the project.