Project Structure

Volāre’s code lives in two repositories. This page tells you what is in each one and where to look when you need to change something.

Repository	What it holds
volare-tech/volare (this one)	All application code: Arkana (backend), the Web (frontend), these docs, the Analytics MCP and E2E tests.
volare-tech/infra-volare	All AWS infrastructure (Terragrunt), server images (Packer + Ansible), monitoring and the deploy workflows. See Infrastructure.

The monorepo

volare/
├── backend/        # Arkana: Laravel 13 + FilamentPHP 5 back office and the REST API
├── frontend/       # The Web: byvolare.com (Astro 7 + React 19 islands)
├── docs/           # This documentation site (Astro Starlight)
├── analytics-mcp/  # Analytics MCP gateway (Google Analytics, Clarity, read-only DB)
├── stagehand/      # Browserbase Stagehand end-to-end checks
├── emails/         # HTML email templates
├── scripts/        # Repo scripts (setup_env.sh, run by the Claude Code session hook)
├── .github/        # GitHub Actions: tests, image builds, tagging, auto-merge
├── .agents/        # Shared AI skills (.claude/skills is a symlink to .agents/skills)
├── .claude/        # Claude Code agents, hooks, plugins and settings
├── .ai/, .codex/, .gemini/  # Rules for other AI tools
├── .mcp.json       # MCP servers for AI tools (laravel-boost, chrome-devtools, nightwatch)
└── AGENTS.md       # Monorepo rules (CLAUDE.md just imports it)

backend/, frontend/ and docs/ each have their own AGENTS.md with the rules for that app. Read the one for the app you are working in.

Where do I find…?

I need to change…	Look in
An Arkana screen (list, form, action)	backend/app/Filament/Resources/<Thing>/ or backend/app/Filament/Pages/
Business rules (pricing, offers, bookings)	backend/app/Services/ — the single place logic lives
An API endpoint the Web calls	backend/routes/api.php → backend/app/Http/Controllers/
A database table	backend/database/migrations/ + backend/app/Models/
A background job	backend/app/Jobs/ (queues are listed in Queue System)
A scheduled task	backend/routes/console.php
An Artisan command	backend/app/Console/Commands/ (full list)
An AI agent or prompt	backend/app/Ai/ (AI System)
An Arkana MCP tool	backend/app/Mcp/Tools/ (Adding a tool)
A transactional email	backend/app/Notifications/ + backend/lang/
A public page on the Web	frontend/src/pages/[market]/
A checkout step	frontend/src/features/checkout/
Production containers or env vars	the infra-volare repository (Infrastructure)

No business logic in Filament or MCP

Filament screens and MCP tools are thin: they call a service in app/Services/. If a screen and a tool need the same rule, it lives once in the service and both use it.

Backend (backend/)

backend/
├── app/
│   ├── Ai/             # laravel/ai agents, tools and prompts
│   ├── Console/        # Artisan commands
│   ├── Enums/          # PHP enums (Role, Permission, statuses…)
│   ├── Filament/       # Arkana: Resources, Pages, Widgets, Actions, Components
│   ├── Http/           # Controllers, Middleware, Requests, Resources (API JSON)
│   ├── Jobs/           # Queue jobs (AerTicket, Pipedrive, NetSuite, offers, emails…)
│   ├── Livewire/       # Livewire components used inside Arkana
│   ├── Mcp/            # Arkana MCP server and tools
│   ├── Models/         # Eloquent models
│   ├── Notifications/  # Emails and database notifications
│   ├── Observers/, Events/, Listeners/
│   ├── Policies/       # Authorization per model
│   ├── Services/       # Business logic, grouped by domain
│   └── …               # Casts, Rules, Support, Traits, ValueObjects, Validation
├── config/             # Laravel config (services.php lists most third parties)
├── database/           # migrations, factories, seeders
├── docker/             # Production images (php-base, php-fpm, queue-worker, nginx)
├── lang/               # Translations (emails, validation)
├── routes/             # api.php, web.php, console.php (schedule), ai.php (MCP), auth.php
├── tests/              # Pest: Feature/ and Unit/
├── compose.yaml        # Local Sail stack
├── phpstan.neon        # Static analysis (level 6)
└── BOOST.md            # Laravel Boost guidelines (regenerated by boost:update)

app/Services/ by domain

Folder / file	Domain
Flights/	AerTicket search, booking, ticketing and the flight cache
Offers/	Offer generation, pricing, domestic-leg rules
Checkout/, Booking/, Payment/	The purchase flow and booking lifecycle
Products/, ProductTemplate*, SupplierTour*, SupplierTours/	Trip content and tours
Allotment/, LastSeats/, Insurance/	Inventory, discounts, Intermundial insurance
Pipedrive/, Netsuite/, ActiveCampaign/, Signaturit/	External integrations
Financial/, Budget/	Revenue dashboard and budget comparison
Ai/, ContentRephraseService, BulkRephraseService	AI content tooling
Cms/, Email/, User/	CMS content, transactional email, user invites

app/Filament/ (Arkana)

Resources map one-to-one to Arkana menu items: Bookings, Offers, ProductTemplates, ProductsByMarket, Suppliers, StopSales, FlightSearches, DynamicFlightCaches, the Cms* resources, Markets, Users and more. Top-level pages include RevenueDashboard, Budget, LastSeats, BookFlight, L2bMonitoring and the sync monitors. The Arkana section documents every menu group.

Frontend (frontend/)

frontend/src/
├── pages/
│   ├── index.astro, 404.astro, login.astro, health.ts, sitemap.xml.ts
│   ├── [market]/           # Everything public is market-scoped: /es/...
│   │   ├── index.astro, home.astro
│   │   ├── destinations/[country].astro, regions/[slug].astro, collections/[slug].astro
│   │   ├── checkout/[offerId].astro, confirmation/[reference].astro, trip/[reference].astro
│   │   ├── last-seats.astro, about-us.astro, celebrity/[slug].astro, legal pages
│   │   └── [...path].astro # product pages and translated paths
│   ├── my-account/         # Logged-in customer area
│   ├── auth/               # Trip and login magic links
│   └── api/checkout/       # Server endpoints used by checkout
├── features/      # Domain UI: checkout, product, trip, lastSeats, landing, client-auth…
├── shared/        # analytics, config (feature toggles), seo, ui, utils, store
├── components/    # Reusable Astro components
├── layouts/       # MainLayout, PublicLayout, MyAccountLayout
├── services/      # API clients
└── middleware.ts  # Market and locale resolution

Routing rules (markets, translated segments, canonical URLs) are in i18n URL Routing. Tailwind CSS v4 is configured through the Vite plugin in astro.config.mjs, not through tailwind.config.mjs.

Documentation (docs/)

Pages are Markdown files in docs/src/content/docs/<section>/. The sidebar is defined in docs/astro.config.mjs: most sections list their folder automatically, but Getting Started, Analytics MCP and Arkana MCP list pages by name, so a new page there also needs a sidebar entry. Run markdownlint before committing:

npx markdownlint-cli2 --fix "docs/src/content/docs/**/*.md"

AI tooling (.claude/, .agents/)

.claude/
├── agents/     # Specialised agents (aerticket-api-agent, offer-doctor, documentation-agent…)
├── skills/     # → ../.agents/skills (slash commands such as /commit, /pr-create)
├── hooks/      # require-skill, block-raw-hex, Pint/markdownlint after edits
├── plugins/    # Repo-local plugin marketplace (laravel-lsp)
├── rules/      # Path-scoped rules (frontend)
└── settings.json

The skills are shared by Claude Code, Codex and Gemini. See Slash Commands and MCP Servers.