# Backend Architecture Specification

## 1. Technology Stack
- **Framework:** Laravel 11
- **PHP Version:** 8.2+
- **Authentication:** Laravel Sanctum (for API) / Session (for Web)

## 2. Design Patterns & Principles
- **Clean Architecture:** Controllers must be thin. All business logic MUST reside in the `Services/` layer.
- **Repository Pattern (Optional):** Use if complex data access logic is required, otherwise use Eloquent directly in Services.
- **Form Requests:** All input validation must be handled via FormRequests (`App\Http\Requests\`).
- **API Responses:** Use a unified `ApiResponseTrait` for all JSON responses.

## 3. Directory Structure Additions
```text
app/
├── Contracts/       # Interfaces for services (e.g., SmsSender.php)
├── Services/        # Business logic classes (e.g., BookingService.php)
├── Traits/          # Reusable traits (e.g., ApiResponseTrait.php)
└── Exceptions/      # Custom exceptions (e.g., InvalidBookingException.php)
```

## 4. Error Handling
- Throw domain-specific exceptions from the Service layer.
- Catch and format exceptions globally in `bootstrap/app.php` or `app/Exceptions/Handler.php`.
- Always return standard HTTP status codes (200, 201, 400, 401, 403, 404, 422, 500).

## 5. Background Processing & Jobs
- List any tasks that should be queued (e.g., sending emails, generating heavy reports, external API integrations).