# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**Laravel API Kit** is an API-only Laravel 12 starter kit following the 2024-2025 REST API ecosystem best practices. No frontend (Blade, Vite, Vue, React) - purely headless API for mobile apps, SPAs, or microservices.

## Tech Stack

- **PHP**: 8.3+
- **Laravel**: 12.x
- **Authentication**: Laravel Sanctum (token-based)
- **API Versioning**: grazulex/laravel-apiroute
- **Query Building**: spatie/laravel-query-builder
- **Data Transformation**: spatie/laravel-data + Laravel API Resources
- **Documentation**: dedoc/scramble (zero-annotation OpenAPI 3.1)
- **Testing**: Pest PHP 3.x

## Key Commands

All commands run via Docker:

```bash
# Run tests
docker compose run --rm app ./vendor/bin/pest

# Run specific test file
docker compose run --rm app ./vendor/bin/pest tests/Feature/Api/V1/AuthTest.php

# Code formatting
docker compose run --rm app ./vendor/bin/pint

# List routes
docker compose run --rm app php artisan route:list

# Clear caches
docker compose run --rm app php artisan config:clear
docker compose run --rm app php artisan cache:clear

# Run migrations
docker compose run --rm app php artisan migrate

# Generate OpenAPI docs
docker compose run --rm app php artisan scramble:export
```

## Architecture

```
app/
├── Actions/              # Single-purpose action classes
├── DTOs/                 # Data Transfer Objects (spatie/laravel-data)
├── Http/
│   ├── Controllers/
│   │   └── Api/
│   │       ├── ApiController.php   # Base controller with ApiResponse trait
│   │       └── V1/                 # Versioned controllers
│   ├── Requests/Api/V1/            # Form Requests per version
│   └── Resources/                  # API Resources
├── Models/
├── Services/             # Business logic services
└── Traits/
    └── ApiResponse.php   # Standardized JSON responses

routes/
├── api.php              # API routes with grazulex/laravel-apiroute versioning

config/
├── apiroute.php         # API versioning config (URI prefix set to empty for Laravel 12)
├── sanctum.php          # Token authentication config
├── scramble.php         # OpenAPI documentation config
└── cors.php             # CORS settings with API headers exposed
```

## API Endpoints

Base URL: `/api/v1`

| Method | Endpoint    | Auth Required | Description          |
|--------|-------------|---------------|----------------------|
| POST   | /register   | No            | Register new user    |
| POST   | /login      | No            | Get auth token       |
| POST   | /logout     | Yes           | Revoke current token |
| GET    | /me         | Yes           | Get current user     |

## Response Format

All responses use the `ApiResponse` trait format:

```json
{
  "success": true,
  "message": "Success message",
  "data": { ... }
}
```

Error responses:
```json
{
  "success": false,
  "message": "Error message",
  "errors": { ... }
}
```

## Adding New API Version

1. Create controller in `app/Http/Controllers/Api/V2/`
2. Create requests in `app/Http/Requests/Api/V2/`
3. Add routes in `routes/api.php`:

```php
ApiRoute::version('v2', function () {
    // V2 routes
})->current();

// Mark V1 as deprecated
ApiRoute::version('v1', function () {
    // V1 routes
})->deprecated('2025-06-01')->sunset('2025-12-01');
```

## Testing

Tests use Pest PHP with Laravel HTTP testing:

```php
it('registers a new user', function () {
    $response = $this->postJson('/api/v1/register', [
        'name' => 'Test User',
        'email' => 'test@example.com',
        'password' => 'password123',
        'password_confirmation' => 'password123',
    ]);

    $response->assertStatus(201)
        ->assertJson(['success' => true]);
});
```

## Rate Limiting

Configured in `AppServiceProvider`:

- **api**: 60 req/min (default)
- **auth**: 5 req/min (login/register protection)
- **authenticated**: 120 req/min (logged-in users)

## Documentation

API documentation auto-generated by Scramble:

- **UI**: `/docs/api`
- **JSON**: `/docs/api.json`

No annotations needed - Scramble analyzes Form Requests and API Resources.