Skip to content
Volāre Documentation

Backend Overview

The backend is Arkana (arkana.byvolare.com) — the brain of Volāre. It is the FilamentPHP back office where the team configures everything (products, offers, pricing, suppliers, bookings, CMS content) and it serves the REST API that feeds the Web (byvolare.com). Built with Laravel 13 and FilamentPHP v5.

Technology Stack

Section titled “Technology Stack”
Component Technology Version
Framework Laravel 13.x
Admin Panel FilamentPHP 5.x
Livewire Livewire 4.x
PHP PHP 8.4+ (Sail ships 8.5)
Database PostgreSQL 18
Queue Database -
Testing Pest 4.x
LLM Integration Laravel AI SDK 0.x

Architecture Overview

Section titled “Architecture Overview”
┌─────────────────────────────────────────────────────────────┐
│                      HTTP Layer                              │
├─────────────────────────────────────────────────────────────┤
│  API Controllers  │  Filament Resources  │  Livewire        │
├─────────────────────────────────────────────────────────────┤
│                    Service Layer                             │
│  AerticketService │ BookingService │ ProductService │ ...   │
├─────────────────────────────────────────────────────────────┤
│                    Data Layer                                │
│  Eloquent Models │ DTOs │ Value Objects                     │
├─────────────────────────────────────────────────────────────┤
│                    Infrastructure                            │
│  PostgreSQL │ Redis │ Queue Jobs │ External APIs            │
└─────────────────────────────────────────────────────────────┘

Key Components

Section titled “Key Components”

Services

Section titled “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
  • CheckoutInsuranceService - Orchestrates Intermundial policy listing, live quoting, and emission for the checkout (Travel Insurance)
  • IntermundialCountryCatalogService - Caches Intermundial’s country catalogue to resolve ISO codes to the proprietary idDyn
  • 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

Section titled “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
  • LeadResource - Contact form leads (read-only, under Customers group)

Queue Jobs

Section titled “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

Section titled “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

Section titled “API Structure”

Multi-Market API

Section titled “Multi-Market API”

Path-based routing for market-specific content:

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

See Multi-Market API for the full endpoint list.

Checkout & Booking API

Section titled “Checkout & Booking API”

Bookings are created through the session-based checkout flow (POST /api/{market}/{lang}/checkout/{offerId} and the per-step PUT endpoints) and read back via the booking-details endpoint. Flight bookings are processed asynchronously on queues.

See Checkout API, Booking Details, and Async Booking.

Database Design

Section titled “Database Design”

Key Models

Section titled “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

Section titled “Relationships”
Product ─┬─ hasMany ─── ProductByMarket
         └─ hasMany ─── Offer


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


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

Authentication & Authorization

Section titled “Authentication & Authorization”

Authentication

Section titled “Authentication”
  • Session-based auth for admin panel
  • Google OAuth integration
  • API tokens for external access

Authorization (RBAC)

Section titled “Authorization (RBAC)”

PHP enums for type-safe roles and permissions:

enum Role: string
{
    case Admin = 'admin';
    case SupplierManager = 'supplier-manager';
    case SalesAgent = 'sales-agent';
    case Finance = 'finance';
}


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

See Roles & Permissions for the full matrix.

Configuration

Section titled “Configuration”

Environment Variables

Section titled “Environment Variables”

Key environment variables:

Terminal window
# 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

Section titled “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

Section titled “Development Commands”
Terminal window
# 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

Section titled “Next Steps”