Flight Orchestrator

The FlightSearchOrchestrator coordinates the multi-step flight search workflow, managing interactions between services and ensuring transactional consistency.

Responsibilities

1. Fetch Search Parameters — Load trip search criteria from database
2. Execute API Search — Call QPX Connect via QPXService
3. Map Responses — Transform API data to internal entities
4. Apply Scoring — Evaluate options against preferences and policies
5. Generate Insights — Create user-facing explanations
6. Persist Results — Save flight options and insights to database

Source Code

Component	Location
Orchestrator	core/orchestrators/flight_search_orchestrator.py
QPX Service	core/services/qpx_service.py
QPX Mapper	core/services/utils/qpx_mapper.py
Insight Service	core/services/insight_service.py

Search Flow

FlightOrchestrator.search_flights()
    │
    ├── 1. Load TripSearch from database
    │       └── uow.trip_searches.get_by_id()
    │
    ├── 2. Build QPX request
    │       └── _build_qpx_request()
    │
    ├── 3. Call QPX API
    │       └── qpx_service.search()
    │
    ├── 4. For each flight result:
    │       │
    │       ├── Create TripOption entity
    │       │   └── _create_trip_option()
    │       │
    │       ├── Extract features
    │       │   └── feature.create()
    │       │
    │       ├── Compute scores
    │       │   └── preference.compute_score()
    │       │
    │       └── Generate insights
    │           └── insight_service.create_insights()
    │
    └── 5. Save all changes
            └── uow.save_changes()

Feature Extraction

The orchestrator extracts features from Flight entities for TTV Scoring. See option_feature/flight/ for feature implementations.

Key features extracted:

• TotalPriceFeature — Total flight price
• NumberOfLegsFeature — Number of segments
• ValidatingCarrierFeature — Ticketing airline
• TotalDurationFeature — Duration in minutes
• DepartureTimeFeature — First leg departure

Policy Compliance

Company policies (see Policy) are evaluated alongside user preferences. Policy violations are recorded as insights.

Transaction Management

The orchestrator uses background_context() for transactional consistency. All operations share the same database session.

warning

If any step fails, the entire transaction is rolled back, ensuring data consistency.

Related Documentation

• QPX Service — External API integration
• TTV Scoring — How scoring works
• Unit of Work — Transaction management