Development Workflow

Daily Development

Starting the Environment

# Start backend containers
cd backend
./vendor/bin/sail up -d

# Start frontend dev server
cd frontend
pnpm dev

# Start documentation (optional)
cd docs
pnpm dev

Development URLs

Service	URL	Purpose
Backend API	http://localhost	Laravel API
Admin Panel	http://localhost/admin	FilamentPHP backoffice
Telescope	http://localhost/telescope	Debug dashboard
Swagger	http://localhost/api/documentation	API docs
Frontend	http://localhost:4321	Astro website
Documentation	http://localhost:4322	This site
Mailpit	http://localhost:8025	Email testing

Git Workflow

Branch Naming

{issue-number}-{short-description}

Examples:

• 123-add-payment-gateway
• 456-booking-validation-error

Commit Messages

Title format: type(scope): description (Conventional Commits, validated by a GitHub Action).

The issue reference goes in the commit body (Refs #ISSUE) and the PR body (Closes #ISSUE), never in the title.

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert Scopes: frontend, backend (required, can use both: backend,frontend)

# Good
git commit -m "feat(backend): add user dashboard with profile management" -m "Refs #123"
git commit -m "fix(backend): booking validation for empty dates" -m "Refs #456"

# Bad
git commit -m "#123 feat(backend): add user dashboard"   # issue ref in title
git commit -m "fix stuff"
git commit -m "WIP"

Slash Commands

Use Claude Code slash commands for common operations:

Skill	Description
/commit [message]	Create commit with Conventional Commits format
/pr-create	Create PR (runs PHPStan check for PHP changes)
/fix-phpstan [path]	Run PHPStan and fix errors
/rebase-master	Rebase onto latest master
/update-master	Switch to master, pull changes, and sync dependencies (local only)
/prune-branches	Delete local branches whose remote tracking branch has been deleted
/task-create [description]	Create a ClickUp task from a description or plan
/task-work [task-id]	Start working on a ClickUp task (setup branch)
/review-comment [text]	Evaluate PR review comment validity
/update-docs	Update documentation for changed services
/work-report [period]	Generate work report/changelog (default: this week)
/db-backup [description]	Create a PostgreSQL backup and upload to S3
/db-restore [filename]	Download a backup from S3 and restore locally

Automated Hooks

.claude/settings.json wires automation around edits:

• SessionStart (startup): runs scripts/setup_env.sh asynchronously to prepare the environment
• PostToolUse (Edit/MultiEdit/Write): on .php files runs composer lint (Pint) and composer analyse:fix (Rector) through Sail; on docs/src/content/docs/**/*.md files runs npx markdownlint-cli2 --fix

Composer Scripts

Canonical local CI entrypoints defined in backend/composer.json:

./vendor/bin/sail composer test                # config:clear + lint:check + analyse:check + phpstan + tests
./vendor/bin/sail composer lint                # Pint (parallel)
./vendor/bin/sail composer analyse             # PHPStan
./vendor/bin/sail composer test:type-coverage  # Pest type coverage (min 100)
./vendor/bin/sail composer dev                 # serve + queue:listen + pail + vite concurrently

Code Quality

PHPStan (Level 6)

All PHP code must pass PHPStan Level 6 analysis:

# Run PHPStan
./vendor/bin/sail exec laravel.test ./vendor/bin/phpstan analyse

# Auto-fix with slash command
/fix-phpstan

Laravel Pint

Format code with Laravel Pint:

./vendor/bin/sail pint

Testing

Run tests with Pest:

# All tests
./vendor/bin/sail artisan test

# Specific test
./vendor/bin/sail artisan test --filter=BookingTest

# With coverage
./vendor/bin/sail artisan test --coverage

Working with Agents

Claude Code includes specialized agents for different tasks:

Agent	Use For
@laravel-core-agent	Models, migrations, controllers, services, core Laravel/Sail work
@filament-admin-agent	Admin resources, form builders, table builders, widgets, custom pages
@laravel-testing-agent	Pest tests, Pint formatting, test coverage, quality assurance
@laravel-debug-agent	Error investigation, logs, performance analysis, Laravel Boost MCP
@aerticket-api-agent	Questions about the AerTicket API
@intermundial-api-agent	Intermundial Nexus API for travel insurance
@documentation-agent	Auditing, pruning, and keeping docs synchronized with code
@offer-doctor	Diagnosing why auto-generated travel offers are missing or fail

Example: Creating a New Feature

For a feature spanning multiple domains, invoke agents in parallel:

User: Create a Booking feature with admin panel and tests

├─ @laravel-core-agent: Model, migration, service
├─ @filament-admin-agent: BookingResource
└─ @laravel-testing-agent: Test suite

Database Operations

Migrations

# Create migration
./vendor/bin/sail artisan make:migration create_bookings_table

# Run migrations
./vendor/bin/sail artisan migrate

# Rollback
./vendor/bin/sail artisan migrate:rollback

# Fresh with seeders
./vendor/bin/sail artisan migrate:fresh --seed

Seeders

# Create seeder
./vendor/bin/sail artisan make:seeder BookingSeeder

# Run seeders
./vendor/bin/sail artisan db:seed

# Specific seeder
./vendor/bin/sail artisan db:seed --class=BookingSeeder

Generating Test Data

After running seeders (db:seed), populate your local environment with test data. Run in this order:

# 1. Seed base data (suppliers, airports, markets)
./vendor/bin/sail artisan db:seed

# 2. Generate hotels
./vendor/bin/sail artisan suppliers:hotels:generate --hotels-per-city=2

# 3. Generate activities
./vendor/bin/sail artisan suppliers:activities:generate --activities-per-city=2

# 4. Generate services linked to hotels and activities
./vendor/bin/sail artisan suppliers:services:generate --type=hotel --count=10
./vendor/bin/sail artisan suppliers:services:generate --type=activity --count=10

# 5. Generate products with flight configs
./vendor/bin/sail artisan products:generate --templates=5 --per-market=1

All commands are interactive when options are omitted, and blocked from running in production.

For detailed options of each command, see Suppliers — Test Data Generation and Products — Test Data Generation.

Tinker

Interactive PHP shell for debugging:

./vendor/bin/sail artisan tinker

# Example queries
>>> User::count()
>>> Booking::with('user')->first()
>>> Product::where('active', true)->get()

Queue Management

Monitor Jobs

# Process jobs
./vendor/bin/sail artisan queue:work

# List failed jobs
./vendor/bin/sail artisan queue:failed

# Retry failed job
./vendor/bin/sail artisan queue:retry {id}

# Clear failed jobs
./vendor/bin/sail artisan queue:flush

Debugging

Laravel Telescope

Access at http://localhost/telescope for:

• Request/response inspection
• Database queries
• Queue jobs
• Exceptions
• Logs

Laravel Boost MCP

Use the Laravel Boost MCP tools:

# Get last error
mcp__laravel-boost__last-error

# Query database
mcp__laravel-boost__database-query "SELECT * FROM users LIMIT 5"

# Execute tinker code
mcp__laravel-boost__tinker "User::count()"

# Search docs
mcp__laravel-boost__search-docs ["queue jobs", "redis"]

Pull Request Workflow

Before Creating PR

1. Run tests: ./vendor/bin/sail artisan test
2. Run PHPStan: /fix-phpstan
3. Format code: ./vendor/bin/sail pint
4. Update documentation if needed

Creating PR

Use the slash command:

/pr-create

This will:

1. Check for uncommitted changes
2. Run PHPStan if PHP files changed
3. Push branch to remote
4. Create PR with template

PR Review

PRs require:

• Passing CI checks (tests, PHPStan)
• Code review approval
• Updated documentation (if applicable)