Project Structure

Monorepo Overview

Volāre uses a monorepo structure with separate directories for backend, frontend, and documentation. The two products are the Web (frontend/ — byvolare.com, the customer-facing online travel agency) and Arkana (backend/ — the back office where everything is configured).

volare/
├── backend/           # Arkana: Laravel 13 + FilamentPHP v5 back office + API
├── frontend/          # Web: byvolare.com storefront (Astro 6)
├── docs/              # Starlight documentation (this site)
├── analytics-mcp/     # Local volare-analytics-mcp Google Analytics MCP server
├── stagehand/         # Browserbase Stagehand E2E tests
├── emails/            # HTML email templates
├── mcp/               # MCP tooling dependencies
├── scripts/           # Repo scripts (e.g. setup_env.sh)
├── .agents/           # Shared agent skills (source of the .claude/skills symlink)
├── .claude/           # Claude Code configurations
├── .github/           # GitHub Actions workflows
├── .mcp.json          # MCP server configuration
├── AGENTS.md          # Source of truth for project guidelines
├── CLAUDE.md          # Pointer file importing @AGENTS.md
└── 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 6 conventions with feature-based organization.

frontend/
├── src/
│   ├── components/        # Reusable Astro components
│   ├── data/              # Static data
│   ├── features/          # Feature-specific components
│   ├── layouts/           # Page layouts
│   │   └── MainLayout.astro
│   ├── mocks/             # Mock data for tests/stories
│   ├── pages/             # File-based routing
│   │   ├── index.astro
│   │   ├── [market]/      # Dynamic market routes
│   │   └── products/      # Product pages
│   ├── react-app/         # React island application code
│   ├── services/          # API/service clients
│   ├── shared/            # Shared utilities
│   ├── styles/            # Global styles
│   ├── test/              # Test setup and helpers
│   └── 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

Claude Code Structure

The .claude/ directory holds AI-assistant configuration:

.claude/
├── agents/            # Specialized agent definitions
├── skills/            # Slash commands (symlink → ../.agents/skills)
├── agent-memory/      # Persistent agent memory
├── hooks/             # Hook scripts
├── plans/             # Saved implementation plans
├── docs/              # Internal Claude docs
└── settings.json      # Permissions, hooks, plugin configuration

The skills symlink points to .agents/skills so the same skill definitions are shared across Claude Code, Codex, and Gemini tooling.

Configuration Files

Root Level

File	Purpose
AGENTS.md	Source of truth for project guidelines, commands, agents, and conventions
CLAUDE.md	Three-line pointer file that imports @AGENTS.md
.mcp.json	MCP server configuration (laravel-boost, chrome-devtools, nightwatch)
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