L-Ami-Fiduciaire/docs/development-guide.md

# Development Guide — L'Ami Fiduciaire

> Generated: 2026-03-08 | Scan Level: Quick

## Prerequisites

- **PHP** 8.2+ (recommended: 8.4)
- **Composer** v2
- **Node.js** 22+
- **npm**
- **Docker** (for Laravel Sail)

## Quick Start

### 1. Clone & Install

```bash
composer install
npm install
```

### 2. Environment Setup

```bash
cp .env.example .env
php artisan key:generate
```

### 3. Start Development Environment (Docker/Sail)

```bash
vendor/bin/sail up -d
vendor/bin/sail artisan migrate
```

### 4. Run Development Servers

```bash
# All-in-one: PHP server + Queue + Logs + Vite (hot reload)
vendor/bin/sail composer run dev

# Or with SSR:
vendor/bin/sail composer run dev:ssr
```

This runs concurrently:
- `php artisan serve` — Laravel application server
- `php artisan queue:listen` — Queue worker
- `php artisan pail` — Log viewer
- `npm run dev` — Vite dev server (HMR)

## Docker Services

| Service | Image | Ports |
|---------|-------|-------|
| laravel.test | sail-8.5/app | 80 (app), 5173 (Vite) |
| mysql | mysql:8.4 | 3306 |
| mailpit | axllent/mailpit | 1025 (SMTP), 8025 (UI) |
| soketi | soketi:latest | 6001 (WS), 9601 (metrics) |

All commands should be prefixed with `vendor/bin/sail` when running inside Docker.

## Build Commands

```bash
# Development build with HMR
npm run dev

# Production build
npm run build

# Production build with SSR
npm run build:ssr
```

## Code Quality

### PHP Formatting (Laravel Pint)

```bash
# Fix formatting (dirty files only)
vendor/bin/sail bin pint --dirty --format agent

# Run all formatting
composer lint

# Check without fixing
composer test:lint
```

### JavaScript/TypeScript Linting

```bash
# ESLint (fix mode)
npm run lint

# Prettier (fix mode)
npm run format

# Prettier (check only)
npm run format:check
```

## Testing

### Running Tests

```bash
# Run all tests
vendor/bin/sail artisan test --compact

# Run with filter
vendor/bin/sail artisan test --compact --filter=testName

# Run specific test file
vendor/bin/sail artisan test --compact tests/Feature/Auth/AuthenticationTest.php

# Full test suite (includes lint + tests)
composer test
```

### Test Structure

- `tests/Feature/` — Feature/integration tests (13 files)
  - `Auth/` — Authentication tests (login, registration, 2FA, email verification, password)
  - `Settings/` — Settings tests (profile, password, 2FA)
  - `DashboardTest.php`, `UserGroupTest.php`
- `tests/Unit/` — Unit tests

### Creating Tests

```bash
# Feature test (default)
vendor/bin/sail artisan make:test --pest MyFeatureTest

# Unit test
vendor/bin/sail artisan make:test --pest --unit MyUnitTest
```

## Key Development Patterns

### Controllers
- Render Inertia pages: `Inertia::render('PageName', ['prop' => $data])`
- Use Form Request classes for validation (never inline validation)
- Invokable controllers for single-action endpoints

### Route Functions (Wayfinder)
- Import from `@/actions/` (controllers) or `@/routes/` (named routes)
- Type-safe route generation for frontend

### Frontend Components
- All pages in `resources/js/pages/` (mapped to routes by Inertia)
- shadcn-vue components in `resources/js/components/ui/`
- Composables in `resources/js/composables/`
- Layouts in `resources/js/layouts/`

### Database
- Use Eloquent models and relationships (avoid `DB::` facade)
- Create Form Requests for all CRUD operations
- Use factories for test data

## Artisan Commands

```bash
# Create model with migration, factory, seeder
vendor/bin/sail artisan make:model ModelName -mfs --no-interaction

# Create controller
vendor/bin/sail artisan make:controller ControllerName --no-interaction

# Create form request
vendor/bin/sail artisan make:request StoreEntityRequest --no-interaction

# Run migrations
vendor/bin/sail artisan migrate

# Fresh migration with seeding
vendor/bin/sail artisan migrate:fresh --seed
```

## CI/CD

GitHub Actions run on push/PR to `develop`, `main`, `master`, `workos`:

1. **Lint** (`lint.yml`): Pint → Prettier → ESLint
2. **Tests** (`tests.yml`): Full test suite on PHP 8.4 and 8.5 matrix