Saad Ibn-Ezzoubayr
35545c2a8f
Initial commit of the L'Ami Fiduciaire SaaS platform built on Laravel 12, Vue 3, Inertia.js 2, and Tailwind CSS 4. Story 0.1 (rename folders to declarations in database) is implemented and code-reviewed: migration, rollback, and 6 Pest tests all passing. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
187 lines
4.0 KiB
Markdown
187 lines
4.0 KiB
Markdown
# 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
|