Project Structure

Monorepo Overview

Volare uses a monorepo structure with separate directories for backend, frontend, and documentation.

volare/
├── backend/           # Laravel 12 + FilamentPHP v5
├── frontend/          # Astro 5 public website
├── docs/              # Starlight documentation (this site)
├── .claude/           # Claude Code configurations
├── .github/           # GitHub Actions workflows
├── CLAUDE.md          # Development guidelines
└── README.md          # Project overview

Backend Structure

The Laravel backend follows standard Laravel conventions with additional organization for services and FilamentPHP.

backend/
├── app/
│   ├── Actions/           # Single-purpose action classes
│   ├── Console/           # Artisan commands
│   ├── DTOs/              # Data Transfer Objects
│   ├── Enums/             # PHP enums (Role, Permission, etc.)
│   ├── Filament/          # FilamentPHP admin panel
│   │   ├── Pages/         # Custom admin pages
│   │   ├── Resources/     # CRUD resources
│   │   └── Widgets/       # Dashboard widgets
│   ├── Http/
│   │   ├── Controllers/   # API controllers
│   │   ├── Middleware/    # HTTP middleware
│   │   └── Requests/      # Form request validation
│   ├── Jobs/              # Queue jobs
│   ├── Models/            # Eloquent models
│   ├── Notifications/     # Notification classes
│   ├── Providers/         # Service providers
│   └── Services/          # Business logic services
├── config/                # Configuration files
├── database/
│   ├── factories/         # Model factories
│   ├── migrations/        # Database migrations
│   └── seeders/           # Database seeders
├── docs/                  # Backend-specific documentation
├── public/                # Public assets
├── resources/
│   └── views/             # Blade templates
├── routes/
│   ├── api.php            # API routes
│   ├── console.php        # Artisan routes
│   └── web.php            # Web routes
├── storage/               # Application storage
├── tests/
│   ├── Feature/           # Feature tests
│   └── Unit/              # Unit tests
├── composer.json          # PHP dependencies
├── compose.yaml           # Docker configuration
├── phpstan.neon           # PHPStan configuration
└── phpunit.xml            # PHPUnit configuration

Key Directories

app/Services/

Business logic layer. Each service encapsulates domain-specific operations.

Services/
├── AerticketCabinetService.php      # AerTicket API HTTP client
├── AirportLookupService.php         # PostgreSQL FTS for airports
├── CurrencyExchangeService.php      # Currency exchange rates
├── GooglePlacesService.php          # Google Places POI integration
├── ProductTemplateService.php       # Product template management
├── Flights/Aerticket/               # AerTicket flight services
├── Payment/                         # Stripe payment gateway
└── Checkout/                        # Checkout session services

app/Filament/

FilamentPHP v5 admin panel components.

Filament/
├── Pages/                    # Custom admin pages
├── Resources/
│   ├── Bookings/             # Booking management
│   ├── FlightBookings/       # Flight booking details
│   ├── FlightSearches/       # Flight search interface
│   ├── ProductTemplates/     # Product templates
│   ├── ProductsByMarket/     # Market-specific products
│   ├── Suppliers/            # Supplier management
│   └── Users/                # User management
└── Widgets/                  # Dashboard widgets

app/Jobs/

Queue jobs for async processing.

Jobs/
├── AerticketCreateBookingJob.php
├── AerticketIssueTicketJob.php
├── AerticketFastlaneTicketingJob.php
├── AerticketRetrieveBookingJob.php
├── AerticketVoidBookingJob.php
├── CreateCheckoutFlightBookingJob.php
├── SearchFlightCacheJob.php
└── GenerateAutoOffersJob.php

Frontend Structure

The Astro frontend follows Astro 5 conventions with feature-based organization.

frontend/
├── src/
│   ├── components/        # Reusable Astro components
│   ├── features/          # Feature-specific components
│   ├── layouts/           # Page layouts
│   │   └── MainLayout.astro
│   ├── pages/             # File-based routing
│   │   ├── index.astro
│   │   ├── [market]/      # Dynamic market routes
│   │   └── products/      # Product pages
│   ├── shared/            # Shared utilities
│   ├── styles/            # Global styles
│   └── env.d.ts           # TypeScript environment
├── public/                # Static assets
├── astro.config.mjs       # Astro configuration
├── package.json           # Node dependencies
├── tailwind.config.mjs    # Tailwind configuration
└── tsconfig.json          # TypeScript configuration

Frontend Key Directories

src/pages/

File-based routing. Each .astro file becomes a route.

pages/
├── index.astro            # / (homepage)
├── health.ts              # /health (API endpoint)
├── [market]/              # /{market} (dynamic)
│   ├── index.astro        # /{market}
│   └── products/
│       └── [slug].astro   # /{market}/products/{slug}
└── products/
    └── [slug].astro       # /products/{slug}

src/layouts/

Reusable page layouts with common elements (header, footer, meta tags).

src/features/

Feature-specific components organized by domain.

Documentation Structure

This documentation site uses Starlight (Astro-based).

docs/
├── src/
│   ├── content/
│   │   └── docs/          # Documentation content
│   │       ├── index.mdx
│   │       ├── getting-started/
│   │       ├── backend/
│   │       ├── frontend/
│   │       ├── architecture/
│   │       ├── operations/
│   │       ├── guides/
│   │       └── reference/
│   └── content.config.ts
├── public/                # Static assets
├── astro.config.mjs       # Starlight configuration
└── package.json

Configuration Files

Root Level

File	Purpose
CLAUDE.md	Development guidelines and AI assistant instructions
.mcp.json	MCP server configuration (Laravel Boost)
README.md	Project overview

Backend

File	Purpose
composer.json	PHP dependencies
phpstan.neon	Static analysis (Level 6)
phpunit.xml	Test configuration
compose.yaml	Docker services
.env	Environment variables

Frontend

File	Purpose
package.json	Node dependencies
astro.config.mjs	Astro configuration
tailwind.config.mjs	Tailwind CSS
tsconfig.json	TypeScript