1. legacy
Itinera API
  • ✈ Itinera API Documentation
  • Docs
    • legacy
      • Itinera — System Overview
      • Technology Stack & Architecture
      • Getting Started Guide
      • Infrastructure
      • Frontend Application
      • Architecture Overview
      • API Reference
      • Backend Services
      • Development Guidelines
    • phases
      • 01. Architecture Overview & Checkout Idempotency
      • Phase 2: Commerce & Checkout Engine
      • Phase 3: Webhooks & Asynchronous Fulfillment
      • Phase 4: Security Perimeter & Authentication
      • Phase 5: Database Schema & Entity Relationships
      • Phase 6: AI Quota & Telemetry Subsystems
      • Phase 7: API Route Matrix & FormRequests
      • Phase 8: Global Exception & Error Handling
      • Phase 9: Frontend Ecosystem & State Management
      • Phase 10: Design System & Component Library
      • Phase 11: Interactive GSAP Animations
      • Phase 12: Deployment & CI/CD Pipeline
      • Phase 13: Testing Strategies
      • Phase 14: Performance & Optimization
      • Phase 15: Developer Onboarding & Runbooks
      • 15-Phase Comprehensive Wiki & Documentation Plan
  • APIs
    • Auth
      • Register a new user
      • Log in a user
      • Log out user
      • Refresh JWT token
      • Forgot password request
      • Reset password verification
      • Get current user profile
      • Update user profile
      • Redirect to Google OAuth
      • Google OAuth Callback
      • Verify email via signed URL
    • Catalog
      • List all countries
      • Get country details
      • List all cities
      • List all regions
      • List all destinations
      • Get destination details
      • Get hotels by destination
      • List all hotels
      • Get hotel details
      • Get reviews for a hotel
      • List all flights
      • Get flight details
      • List all restaurants
      • Get restaurant details
      • List all attractions
      • Get current weather
      • Submit review for an entity
      • Delete review
      • Toggle favourite status for entity
      • List my submitted reviews
    • Bookings
      • Book a tour destination
    • V1 Aliases
      • V1 List all countries
      • V1 Get country details
      • V1 List all cities
      • V1 List all destinations
      • V1 Get destination details
      • V1 Get hotels by destination
      • V1 List all hotels
      • V1 Get hotel details
      • V1 Get reviews for a hotel
      • V1 List all flights
      • V1 Get flight details
      • V1 List all restaurants
      • V1 Get restaurant details
      • V1 List all attractions
      • V1 Get attraction details
      • V1 List all regions
      • V1 Get weather details
    • Trips
      • List user trips
      • Create a new trip
      • Get trip details
      • Update trip details
      • Delete a trip
      • Get creation metadata
      • Attach items to a trip
      • Update trip item
      • Detach items from a trip
      • Fork a trip
    • Conversations
      • List user conversations
      • Start a new conversation
      • Get conversation details
      • List messages in conversation
      • Send message to conversation
      • Mark conversation as read
    • Commerce Plans
      • List public plans
      • Get public plan details
    • Commerce Subscriptions
      • Subscribe to a plan
      • Upgrade active plan
      • Get active subscription info
      • Cancel active subscription
    • Commerce Checkout
      • Initiate Paymob payment checkout
    • Integrations
      • Paymob status webhook callback
      • Paymob redirect return callback
    • System Settings & Support
      • Submit public contact message
      • Subscribe to system newsletter
      • Get list of my reports
      • List all notifications
      • Mark single notification as read
      • List available surveys
      • Submit answers for survey
      • Get survey details
      • Update survey details
      • Delete survey response
    • AI Tools
      • Enhance itinerary details using AI
      • Request AI review of itinerary
      • Plan route using AI assistance
      • Get AI quota remaining details
      • Chat with AI Concierge assistant
      • Get AI Review progress by ID
    • Agency Integration
      • Request agency assignment
      • List agency active tasks
      • List agency managed trips
      • Get agency total earnings
      • Get agency profile details
      • Update agency profile details
    • Admin User Management
      • List users inside admin dashboard
      • Get user profile
      • Set user active status
      • Block user profile
    • Admin Catalog Moderation
      • Create new catalog category
      • Create new catalog destination
      • Create new hotel catalog record
      • Create new flight catalog record
      • Create new restaurant catalog record
      • Create new attraction catalog record
  • Schemas
    • User
    • ErrorResponse
    • Trip
    • Destination
    • Hotel
    • Flight
    • Restaurant
    • Attraction
    • Booking
    • Review
    • Agency
    • Survey
  1. legacy

Backend Services

Table of Contents#

1.
Service Catalogue
2.
AI Services (Groq)
3.
Commerce & Payments
4.
Reporting Pipeline
5.
Weather Service
6.
Fixture & Seeding Services
7.
Jobs, Listeners, Mail, Notifications
8.
Console Commands

Service Catalogue#

Diagram sources: app/Services tree

AI Services (Groq)#

GroqService wraps lucianotonet/groq-laravel:
enhance(string $content) — text enhancement with temperature 0.5; failures are logged and rethrown as a user-safe RuntimeException.
generateAi(AiTripRequest $request) — full itinerary synthesis from destination country, budget tier and interests.
AI review endpoints (AIController::review) feed trip JSON to the LLM for automated feedback.
Quota enforcement: every call routes through AiUsageService; counters live in Redis/cache and surface at GET /me/ai-quota. Rate limiting adds throttle:ai on top.
Config: config('groq.model'), default llama-3.1-8b-instant (services.php#L59-L62).
Section sources: GroqService.php, Trips/AIController.php

Commerce & Payments#

ConcernImplementation
Checkout entryPOST /payments/initiate → CheckoutController::initiate with InitiateCheckoutRequest
Strategy selectionCheckoutStrategyFactory: subscription, trip_package, trip_fork
PricingPriceCalculatorService (taxes/discounts, currency via Support/Enums/Currency)
GatewayPaymobGateway implements PaymentGatewayInterface over PaymobClient
WebhooksWebhookService verifies HMAC SHA-512 signature before order state transitions; routes excluded from CSRF (/payments/webhook, /paymob/webhook, /paymob-v1/webhook)
SubscriptionsPlanController subscribe/upgrade/cancel; expiry handled by command + tests (SubscriptionExpiryTest)
Agency marketplaceassignment approve/decline state machine with InvalidStateTransitionException guard
Section sources: Commerce controllers, Commerce services, .env.example keys

Reporting Pipeline#

Default filter is "All Time" per product spec; seeded telemetry provides 60+ paid orders/payments so reports have data out of the box.
Diagram sources: System/ReportController.php, Jobs/GenerateReportJob.php, Queries/ReportQuery.php

Weather Service#

OpenMeteoService fetches current conditions per coordinate pair; WeatherController::show is double-protected by Redis response caching and throttle:weather. Abuse and cache behaviour covered by tests/Feature/System/WeatherAbuseTest and WeatherCacheTest.

Fixture & Seeding Services#

app/Services/Catalog/Fixtures/* load deterministic datasets from database/seeders/fixtures/*.json — countries, cities, hotels, flights, restaurants, attractions — optionally geocoding through OpenStreetService. Console commands sync:fixtures and sync:cities refresh them without full reseeds.

Jobs, Listeners, Mail, Notifications#

Jobs: GenerateReportJob, GeocodeDestinationJob.
Listeners: FulfillOrderListener (PaymentSucceeded → fulfilment + mails), HandlePaymentFailed.
Mail: 10 branded templates incl. PaymentSuccessMail, TripBookedMail, ReviewFlaggedMail, WelcomeMail.
Notifications: database channel mirrors each mail event (AppNotification base).

Console Commands#

CommandPurpose
seed:freshorchestrated fresh seed (SeedFresh.php)
sync:fixtures / sync:citiesrefresh fixture-driven catalog data
expire:stale-orders / expire:stale-subscriptions / expire:password-tokensscheduled housekeeping
export:postmangenerate Postman collection from routes (ExportPostman.php)
Modified at 2026-08-25 22:41:45
Previous
API Reference
Next
Development Guidelines
Built with