# Finance Backend - Laravel API

A Laravel 13 REST API project serving as a finance backend. Built with a focus on type safety, standardized responses, and comprehensive testing.

## Project Overview

- **Framework:** Laravel 13.x (PHP 8.3)
- **Authentication:** Laravel Sanctum (Token-based)
- **Database:** PostgreSQL (implied by typical usage, check `.env`)
- **API Documentation:** [Scramble](https://scramble.dedoc.co/) (Automatic OpenAPI documentation)
- **Testing:** [Pest](https://pestphp.com/)
- **Code Quality:** [PHPStan](https://phpstan.org/), [Laravel Pint](https://laravel.com/docs/pint), [Rector](https://getrector.org/)
- **API Versioning:** `grazulex/laravel-apiroute`

## Architecture & Conventions

### API Standard
- **Routes:** Versioned routes are located in `routes/api/v{version}.php`.
- **Controllers:** Extend `App\Http\Controllers\Api\ApiController`.
- **Responses:** Standardized JSON responses via `App\Traits\ApiResponse`.
    - `success($data, $message, $code)`
    - `error($message, $code, $errors)`
    - `created($data, $message)`
- **Request Validation:** Use dedicated Form Requests in `app/Http/Requests/Api/V1`.
- **Resources:** Use Eloquent Resources in `app/Http/Resources` for response formatting.

### Development Workflow
- **Models:** Use PHP 8.1+ Attributes for `#[Fillable]` and `#[Hidden]` where possible (consistency varies, follow `User.php` for new models).
- **Migrations:** Standard Laravel migrations in `database/migrations`.
- **Transactions:** Wrap database mutations in `DB::transaction()` within controllers or services.

## Key Commands

### Environment Setup
```bash
cp .env.example .env
composer install
php artisan key:generate
php artisan migrate --seed
```

### Development & Testing
- **Run Tests:** `php artisan test` or `composer test`
- **Static Analysis:** `composer test:types` (PHPStan)
- **Linting:** `composer lint` (Pint + Rector)
- **API Docs:** Access via `/docs/api` (standard Scramble path)

### Common Artisan Commands
- `php artisan make:controller Api/V1/NameController --api`
- `php artisan make:request Api/V1/StoreNameRequest`
- `php artisan make:resource NameResource`

## Directory Structure

- `app/Http/Controllers/Api/V1`: API Version 1 controllers.
- `app/Http/Requests/Api/V1`: Validation logic for V1.
- `app/Http/Resources`: Response transformation layers.
- `app/Models`: Eloquent models with relationships.
- `app/Traits/ApiResponse.php`: Standard response helper.
- `routes/api/v1.php`: API V1 route definitions.
- `tests/Feature/Api/V1`: Functional tests for the API.