Project Structure

Monorepo Overview

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

volare/
├── backend/           # Laravel 12 + FilamentPHP v4
├── 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
├── docker-compose.yml     # Docker configuration
├── phpstan.neon           # PHPStan configuration
└── phpunit.xml            # PHPUnit configuration

Key Directories

app/Services/

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

Services/
├── AerticketService.php       # Flight search & booking
├── AirportSearchService.php   # PostgreSQL FTS for airports
├── BookingService.php         # Booking management
├── OfferService.php           # Travel offers
└── ProductService.php         # Market products

app/Filament/

FilamentPHP v4 admin panel components.

Filament/
├── Pages/
│   └── Dashboard.php
├── Resources/
│   ├── ProductResource.php
│   ├── BookingResource.php
│   └── UserResource.php
└── Widgets/
    ├── StatsOverview.php
    └── RecentBookings.php

app/Jobs/

Queue jobs for async processing.

Jobs/
├── ProcessBooking.php
├── SyncFlightPrices.php
└── SendNotification.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.js     # Tailwind configuration
└── tsconfig.json          # TypeScript configuration

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
docker-compose.yml	Docker services
.env	Environment variables

Frontend

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