Backend Overview

The Volare backend is built with Laravel 12 and FilamentPHP v5, providing a robust foundation for the travel platform.

Technology Stack

Component	Technology	Version
Framework	Laravel	12.x
Admin Panel	FilamentPHP	5.x
Livewire	Livewire	4.x
PHP	PHP	8.5
Database	PostgreSQL	18
Queue	Database	-
Testing	Pest	3.x
LLM Integration	Laravel AI SDK	0.x

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                      HTTP Layer                              │
├─────────────────────────────────────────────────────────────┤
│  API Controllers  │  Filament Resources  │  Livewire        │
├─────────────────────────────────────────────────────────────┤
│                    Service Layer                             │
│  AerticketService │ BookingService │ ProductService │ ...   │
├─────────────────────────────────────────────────────────────┤
│                    Data Layer                                │
│  Eloquent Models │ DTOs │ Repositories                      │
├─────────────────────────────────────────────────────────────┤
│                    Infrastructure                            │
│  PostgreSQL │ Redis │ Queue Jobs │ External APIs            │
└─────────────────────────────────────────────────────────────┘

Key Components

Services

Business logic is encapsulated in service classes:

• AerticketCabinetService - HTTP client, authentication, and environment switching for AerTicket API
• AerticketSearchService - Flight search via AerTicket
• IntermundialClientService - HTTP client, authentication, and environment routing for Intermundial insurance API
• ProductTemplateService - Product template management
• SupplierTourService - Tour completion tracking, hotel/activity/transfer assignment management
• AirportLookupService - PostgreSQL full-text search for airports
• CurrencyExchangeService - Currency exchange rate management

Filament Resources

Admin panel CRUD operations:

• ProductResource - Travel products management
• BookingResource - Booking management
• FlightBookingResource - Flight booking details
• UserResource - User management with RBAC
• OfferResource - Offer management

Queue Jobs

Async processing with database queue:

• AerticketCreateBookingJob - Create flight bookings asynchronously
• AerticketIssueTicketJob - Issue tickets for confirmed bookings
• AerticketFastlaneTicketingJob - Fast-track ticket issuance
• SearchFlightCacheJob - Dynamic flight cache searches
• CreateCheckoutFlightBookingJob - Checkout flight booking job triggered from booking admin actions
• GenerateAutoOffersJob - Generate offers automatically

AI Integration

AI-powered content generation via Laravel AI SDK (laravel/ai) with OpenRouter as default provider:

• ProductTemplateAIService - Generate product descriptions from titles or raw trip data
• ProductByMarketTranslationService - Translate product content to target locales
• SupplierHotelGeneratorService - Generate realistic hotel data for testing

Configuration: OPENROUTER_API_KEY, OPENROUTER_BASE_URL, OPENROUTER_MODEL environment variables. See config/ai.php.

API Structure

Multi-Market API

Path-based routing for market-specific content:

GET /api/{market}/products         # List products for market
GET /api/{market}/products/{id}    # Get product by ID
GET /api/{market}/products/slug/{slug}  # Get product by slug
GET /api/{market}/config           # Get market configuration

Booking API

Async booking workflow:

POST /api/bookings                 # Create booking
GET  /api/bookings/{id}            # Get booking status
POST /api/bookings/{id}/confirm    # Confirm booking

Database Design

Key Models

• Product - Base travel products
• ProductByMarket - Market-specific product versions
• Booking - Customer bookings
• FlightBooking - Flight-specific booking data
• Offer - Combined product + flight offers
• Airport - Airport data with FTS support

Relationships

Product ─┬─ hasMany ─── ProductByMarket
         └─ hasMany ─── Offer

Booking ─┬─ belongsTo ─ User
         └─ hasMany ─── FlightBooking (one per leg)

Offer ──┬─ belongsTo ── ProductByMarket
        └─ belongsTo ── FlightBooking

Authentication & Authorization

Authentication

• Session-based auth for admin panel
• Google OAuth integration
• API tokens for external access

Authorization (RBAC)

PHP enums for type-safe roles and permissions:

enum Role: string
{
    case Admin = 'admin';
    case SupplierManager = 'supplier-manager';
}

enum Permission: string
{
    case ViewUser = 'view_user';
    case CreateUser = 'create_user';
    // ... 85 total permissions
}

Configuration

Environment Variables

Key environment variables:

# Application
APP_ENV=production
APP_DEBUG=false

# Database
DB_CONNECTION=pgsql
DB_HOST=pgsql
DB_DATABASE=volare

# Queue
QUEUE_CONNECTION=database

# External APIs
AERTICKET_ENVIRONMENT=uat
AERTICKET_LOGIN=your_api_login
AERTICKET_PASSWORD=your_api_password

# Intermundial
INTERMUNDIAL_ENVIRONMENT=sandbox
INTERMUNDIAL_BASE_URL=
INTERMUNDIAL_USERNAME=...
INTERMUNDIAL_PASSWORD=...
INTERMUNDIAL_API_KEY=...

Intermundial Endpoints

• https://apigw-dev.intermundial.com/aks/api is the real API gateway for pre/sandbox integration tests.
• https://apigw.intermundial.com/aks/api is the real API gateway for production.
• https://apidoc.intermundial.com/ is documentation only (portal), not an API base URL for requests.
• Set INTERMUNDIAL_BASE_URL to the gateway you want to use in each deployment (sandbox or production).

Development Commands

# Start development environment
./vendor/bin/sail up -d

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

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

# Clear cache
./vendor/bin/sail artisan optimize:clear

Next Steps

• API Reference - Detailed API documentation
• Services - Service documentation
• Authentication - RBAC details