# Coding Standards

## PHP (Backend)

### Style
- Follow **PSR-12** — enforced via [Laravel Pint](https://laravel.com/docs/pint)
- Run before commit: `./vendor/bin/pint`

### Architecture

```
app/
├── Domain/{Module}/Actions/    # Business logic (single responsibility)
├── Http/Controllers/Api/V1/    # Thin controllers
├── Http/Requests/              # Validation
├── Http/Resources/             # API response transformers
├── Services/                   # Shared services
├── Policies/                   # Authorization
└── Events/ + Listeners/        # Side effects
```

### Conventions

| Item | Convention |
|------|------------|
| Controllers | Return `JsonResponse` via `$this->success()` / `$this->error()` |
| API envelope | `{ success, data, message }` always |
| Actions | `execute(array $data): Model` — one action per class |
| Models | Use `$fillable`, `$casts`, relationships |
| Enums | PHP 8.1 backed enums in `app/Enums/` |
| Routes | Prefix `/api/v1`, named by resource |

### Database
- Use **migrations** for all schema changes
- Use **Eloquent** or Query Builder — never raw SQL with user input
- Add indexes for foreign keys and common query patterns

### Testing
- Feature tests for API endpoints
- Unit tests for services/actions
- Use `RefreshDatabase` + fixture traits

## TypeScript (Frontend)

### Style
- **Functional components** with hooks
- **TypeScript strict** — no `any` unless justified
- Run linter: `npm run lint`

### Structure

```
src/
├── components/ui/          # Reusable UI (Button, Card)
├── components/features/    # Domain components (FieldCard)
├── hooks/                  # Custom hooks (useBooking)
├── services/               # API clients (bookingApi)
├── store/                  # Zustand stores
├── types/                  # Shared TypeScript types
└── pages/                  # Route pages
```

### Conventions

| Item | Convention |
|------|------------|
| API calls | TanStack Query hooks wrapping service functions |
| State | Zustand for client state, React Query for server state |
| Forms | react-hook-form + zod schemas |
| Styling | Tailwind CSS v4 utility classes |
| Imports | `@/` path alias |

## API Documentation

Add Scribe annotations to new endpoints:

```php
/**
 * Create resource
 *
 * @group Group Name
 * @authenticated
 * @response 201 scenario="Success" {"success":true,"data":{},"message":"..."}
 */
public function store(StoreRequest $request): JsonResponse
```

Regenerate: `php artisan scribe:generate`

## Security Checklist

- [ ] Validate all input via Form Requests
- [ ] Authorize via Policies
- [ ] Never expose `.env` or secrets
- [ ] Use parameterized queries (Eloquent)
- [ ] Rate limit sensitive endpoints