Start Here

Welcome to Volāre. This documentation is large, so do not read it top to bottom. Follow this path instead: each step lists a few pages and what you should be able to do afterwards. Keep the Glossary open in another tab.

What Volāre is, in one minute

Volāre sells multi-day trips (flights + hotels + activities) online. There are two main services:

• The Web — byvolare.com, where customers find a trip, pick a departure date and pay. It is an Astro site in frontend/.
• Arkana — the back office where the team builds those trips, prices them and handles bookings. It also serves the API the Web reads. It is a Laravel + Filament app in backend/.

A trip is built like this: a supplier provides hotels and activities → we package them into a tour → the tour is published to a market (a country) as a product → the system pairs the product with cached flights to create bookable offers (one per departure date) → a customer buys an offer and it becomes a booking.

flowchart LR
  S[Supplier<br/>hotels, activities] --> T[Tour]
  T --> P[Product by market]
  F[Flight cache<br/>AerTicket] --> O
  P --> O[Offers<br/>one per date]
  O -->|checkout| B[Booking]

Day 1 — Get it running

1. Installation — run Arkana, the Web and these docs locally.
2. Development Workflow — branches, commits, PRs.
3. MCP Servers — connect your AI tools to the project.

You can now: sign in to Arkana locally, open the Web on localhost:4321, and know how a change reaches master.

Day 2 — Learn the business through Arkana

Read the Arkana section with Arkana open next to it. It follows the menu, one page per group: Suppliers, Products, Customers, Flights, Markets, CMS, System.

You can now: explain the path supplier → tour → product → offer → booking, and find each of them in Arkana.

Day 3 — How the system is built

1. Architecture Overview — the big picture: apps, data, integrations.
2. Project Structure — where code lives.
3. Backend Overview and Frontend Overview.
4. Products System and Offers — the heart of the domain. Skim; come back when you work on them.

You can now: find the service, model and Filament resource behind any Arkana screen.

Day 4 — How it runs in production

1. Infrastructure Overview — AWS, environments, servers, the infra-volare repository.
2. Deployment — from a merged PR to code running in production.
3. Server Access — getting a shell on a server.
4. Health Monitoring and Monitoring and Alerts.

You can now: say which server runs what, follow a release from merge to production, and know where alerts come from.

Day 5 — Go deep on your area

Pick the section that matches your first task:

If you work on…	Read
Flights	AerTicket, Dynamic Flight Cache, Flight Search
Checkout and payments	Checkout API, Checkout Flow, Payment, Booking Lifecycle
Suppliers and content	Suppliers, Products by Market, AI System
The public website	Frontend Overview, i18n URL Routing, Feature Toggles, CMS API
Integrations	Pipedrive, NetSuite, Insurance, Signaturit
Infrastructure	the whole Infrastructure section

Rules everyone follows

• Never commit to master; every change is a branch + PR.
• PHP, Composer and Artisan always run through Sail (./vendor/bin/sail).
• Business logic lives in backend/app/Services/, never inside Filament screens or MCP tools.
• Prices are computed once, in the backend. The Web never calculates a price.
• Code, comments, commits and docs are in English.
• When you change a documented behaviour, update its page in the same PR (/update-docs).

When you are stuck

• Search this site (top bar) — most error names and command names are indexed.
• Artisan Commands lists every operational command.
• Ask in the team chat; mention the page you read so it can be improved.