Architecture Overview

Volare is a travel platform built as a monorepo with a Laravel backend and Astro frontend.

System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Clients                                  │
│    Web Browser    │    Mobile App    │    Admin Panel            │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Cloudflare (CDN/Edge)                        │
│         Static Assets  │  Edge Caching  │  DDoS Protection       │
└─────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
┌─────────────────────────┐     ┌─────────────────────────┐
│   Astro Frontend        │     │   Laravel Backend       │
│   (Cloudflare Pages)    │     │   (Docker/AWS)          │
│                         │     │                         │
│   - SSR/SSG pages       │────▶│   - REST API            │
│   - Product pages       │     │   - FilamentPHP Admin   │
│   - Market routing      │     │   - Queue workers       │
└─────────────────────────┘     │   - Background jobs     │
                                └─────────────────────────┘
                                          │
              ┌───────────────────────────┼───────────────────────────┐
              ▼                           ▼                           ▼
┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐
│   PostgreSQL        │     │   Redis             │     │   External APIs     │
│                     │     │                     │     │                     │
│   - Primary DB      │     │   - Cache           │     │   - AerTicket       │
│   - Full-text search│     │   - Queue driver    │     │   - Payment gateway │
│   - Job storage     │     │   - Sessions        │     │   - Email service   │
└─────────────────────┘     └─────────────────────┘     └─────────────────────┘

Monorepo Structure

volare/
├── backend/           # Laravel 12 + FilamentPHP v4
│   ├── app/           # Application code
│   ├── config/        # Configuration
│   ├── database/      # Migrations, seeders
│   ├── routes/        # API and web routes
│   └── tests/         # Pest tests
│
├── frontend/          # Astro 5 + Tailwind CSS v4
│   ├── src/           # Source code
│   │   ├── pages/     # File-based routing
│   │   ├── components/
│   │   └── layouts/
│   └── public/        # Static assets
│
├── docs/              # Starlight documentation
│   └── src/content/   # Documentation content
│
└── .claude/           # Claude Code configuration
    ├── agents/        # Specialized AI agents
    └── commands/      # Custom slash commands

Backend Architecture

Layered Architecture

┌─────────────────────────────────────────────┐
│              Presentation Layer              │
│   Controllers  │  Resources  │  Middleware   │
├─────────────────────────────────────────────┤
│              Application Layer               │
│   Services  │  Actions  │  Jobs  │  Events   │
├─────────────────────────────────────────────┤
│               Domain Layer                   │
│   Models  │  DTOs  │  Enums  │  Policies     │
├─────────────────────────────────────────────┤
│            Infrastructure Layer              │
│   Database  │  Cache  │  Queue  │  APIs      │
└─────────────────────────────────────────────┘

Key Design Patterns

Pattern	Usage
Service Layer	Business logic encapsulation
Repository	Data access abstraction
DTOs	Data transfer between layers
Actions	Single-purpose operations
Form Requests	Input validation
Resources	API response transformation
Policies	Authorization logic

Data Flow

API Request Flow

1. HTTP Request arrives
2. Route matched, middleware executed
3. Controller receives request
4. Form Request validates input
5. Service layer processes business logic
6. Repository fetches/saves data
7. Resource transforms response
8. JSON response returned

Queue Job Flow

1. Job dispatched from application
2. Job serialized to database
3. Queue worker picks up job
4. Job handler executes
5. Success: job deleted
6. Failure: retry or move to failed_jobs

Database Design

Core Models

Model	Purpose
Product	Base travel products
MarketProduct	Market-specific product versions
ProductByMarketTranslation	Localized content
Booking	Customer bookings
FlightBooking	Flight-specific booking data
Offer	Combined product + flight offers
Market	Geographic markets
Airport	Airport data with FTS
User	Admin users with RBAC

Key Relationships

Product (template)
    └── hasMany: MarketProduct (per market)
            └── hasMany: ProductByMarketTranslation (per locale)

Booking
    └── belongsTo: User
    └── hasOne: FlightBooking
            └── belongsTo: Airport (departure, arrival)

Offer
    └── belongsTo: MarketProduct
    └── belongsTo: FlightBooking

Caching Strategy

Cache Layers

Layer	Technology	Purpose
CDN	Cloudflare	Static assets, edge caching
Application	Redis	Query results, sessions
Database	PostgreSQL	Query plan caching

Cache Patterns

• Cache-aside: Load on miss, store on read
• Write-through: Update cache on write
• TTL-based: Automatic expiration

Queue Architecture

Queue Priorities

High Priority:    aerticket-tickets
Medium Priority:  aerticket-bookings
Normal Priority:  default

Job Categories

Category	Queue	Examples
Ticketing	aerticket-tickets	Issue tickets
Booking	aerticket-bookings	Create/update bookings
Notifications	default	Emails, SMS
Sync	default	Price updates, inventory

Security Architecture

Authentication

• Admin Panel: Session-based with CSRF
• API: Token-based (Sanctum)
• OAuth: Google integration

Authorization

• RBAC: Role-based access control
• Policies: Model-level permissions
• Gates: Feature-level permissions

Data Protection

• Encryption: Sensitive data at rest
• HTTPS: All traffic encrypted
• Input validation: Form requests
• Output encoding: XSS prevention

Deployment Architecture

Development

Docker Compose
├── Laravel (port 80)
├── PostgreSQL (port 5432)
├── Redis (port 6379)
├── Queue Worker
└── Mailpit (port 8025)

Production

AWS / Cloudflare
├── Frontend: Cloudflare Pages
├── Backend: AWS ECS / EC2
├── Database: AWS RDS (PostgreSQL)
├── Cache: AWS ElastiCache (Redis)
├── Queue: Amazon SQS
└── Storage: AWS S3

Monitoring & Observability

Tools

Tool	Purpose
Laravel Telescope	Development debugging
Laravel Horizon	Queue monitoring
Structured Logging	Application logs
Health Endpoints	Service health checks

Health Checks

GET /health          # Application health
GET /api/health      # API health
GET /horizon         # Queue dashboard
GET /telescope       # Debug dashboard