# hbuz/aafe-airways architecture

> Architecture diagram of the GitHub repository hbuz/aafe-airways, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hbuz/aafe-airways
- Repository: https://github.com/hbuz/aafe-airways

## Overview

AAFE is a two-service airline fare-calculation product. The primary workflow validates a submitted itinerary, obtains airport details, calculates leg distances and pricing components, then returns the fare and tax. A separate admin workflow refreshes the in-memory served-station registry. The README documents both Haversine and Geodesic distance strategies and airport-specific charges. Some fare-engine modules and the Geodesic implementation were not excerpted; their nodes reflect paths and capabilities in the tree/README, and uncertain links are omitted.

Main entry points: [`aafe-fare-engine/src/main/java/com/aafe/fareengine/service/FareCalculationService.java`](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/service/FareCalculationService.java) (Fare orchestrator), [`aafe-fare-engine/src/main/java/com/aafe/fareengine/controller/ItineraryController.java`](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/controller/ItineraryController.java) (Itinerary endpoint), [`aafe-fare-engine/src/main/java/com/aafe/fareengine/validation/ItineraryValidator.java`](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/validation/ItineraryValidator.java) (Itinerary validation), [`aafe-fare-engine/src/main/java/com/aafe/fareengine/service/AirportClient.java`](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/service/AirportClient.java) (Airport client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_airports["Airport data"]
  node_airport_client["Airport client<br/>[AirportClient.java]"]
  node_airports_api["Airports API<br/>[index.ts]"]
  node_airport_model["Airport data model<br/>[model.ts]"]
end

subgraph group_api["Fare API"]
  node_itinerary_controller["Itinerary endpoint"]
  node_admin_controller["Admin endpoint"]
end

subgraph group_validation["Itinerary rules"]
  node_itinerary_validator["Itinerary validation"]
  node_valid_itinerary["Validation annotation"]
  node_station_registry["Station registry"]
end

subgraph group_calculation["Fare calculation"]
  node_fare_service["Fare orchestrator"]
  node_airport_mapper["Airport coordinate mapper<br/>[AirportMapper.java]"]
  node_distance_calculator["Distance selector"]
  node_distance_strategy["Distance strategy contract"]
  node_haversine_strategy["Haversine strategy"]
  node_accurate_strategy["Geodesic strategy"]
  node_haversine_util["Haversine calculation<br/>[HaversineUtil.java]"]
  node_service_charge["Service charges"]
  node_fare_result["Fare result<br/>[Itinerary.java]"]
  node_fare_breakdown["Fare breakdown<br/>[FareBreakdown.java]"]
end

subgraph group_support["Configuration and errors"]
  node_fare_properties["Fare rules"]
  node_charge_properties["Charge rules"]
  node_error_handler["API error mapping"]
  node_cache_config["Cache configuration<br/>[CacheConfig.java]"]
end

node_traveler(("API caller"))

node_traveler -->|"requests fare"| node_itinerary_controller
node_itinerary_controller -->|"validates input"| node_valid_itinerary
node_valid_itinerary -->|"delegates validation"| node_itinerary_validator
node_itinerary_validator -->|"checks stations"| node_station_registry
node_itinerary_validator -->|"reads restrictions"| node_fare_properties
node_itinerary_controller -->|"calculates fare"| node_fare_service
node_fare_service -->|"fetches airport data"| node_airport_client
node_airport_client -->|"requests airport details"| node_airports_api
node_airports_api -->|"uses data model"| node_airport_model
node_fare_service -->|"maps coordinates"| node_airport_mapper
node_fare_service -->|"calculates leg distance"| node_distance_calculator
node_fare_service -->|"reads pricing rules"| node_fare_properties
node_distance_calculator -.->|"selects strategy"| node_distance_strategy
node_haversine_strategy -->|"uses formula"| node_haversine_util
node_fare_service -->|"calculates charges"| node_service_charge
node_service_charge -->|"reads charge rules"| node_charge_properties
node_fare_service -->|"builds breakdown"| node_fare_breakdown
node_fare_service -->|"returns itinerary"| node_fare_result
node_traveler -->|"requests refresh"| node_admin_controller
node_admin_controller -->|"refreshes stations"| node_station_registry
node_cache_config -.->|"caches responses"| node_airport_client
node_error_handler -.->|"returns API errors"| node_traveler

click node_itinerary_controller "https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/controller/ItineraryController.java"
click node_admin_controller "https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/controller/AdminController.java"
click node_itinerary_validator "https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/validation/ItineraryValidator.java"
click node_valid_itinerary "https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/validation/ValidItinerary.java"
click node_station_registry "https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/service/StationRegistryService.java"
click node_fare_service "https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/service/FareCalculationService.java"
click node_airport_client "https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/service/AirportClient.java"
click node_airports_api "https://github.com/hbuz/aafe-airways/blob/main/airports-api/src/index.ts"
click node_airport_model "https://github.com/hbuz/aafe-airways/blob/main/airports-api/src/model.ts"
click node_airport_mapper "https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/mapper/AirportMapper.java"
click node_distance_calculator "https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/service/DistanceCalculator.java"
click node_distance_strategy "https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/service/distance/DistanceStrategy.java"
click node_haversine_strategy "https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/service/distance/HaversineDistanceStrategy.java"
click node_accurate_strategy "https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/service/distance/AccurateDistanceStrategy.java"
click node_haversine_util "https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/util/HaversineUtil.java"
click node_service_charge "https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/service/ServiceChargeCalculator.java"
click node_fare_result "https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/model/Itinerary.java"
click node_fare_breakdown "https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/model/FareBreakdown.java"
click node_fare_properties "https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/config/FareEngineProperties.java"
click node_charge_properties "https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/config/ServiceChargeProperties.java"
click node_error_handler "https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/exception/GlobalExceptionHandler.java"
click node_cache_config "https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/config/CacheConfig.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_airport_client,node_airports_api,node_airport_model toneBlue
class node_itinerary_controller,node_admin_controller toneAmber
class node_itinerary_validator,node_valid_itinerary,node_station_registry,node_traveler toneMint
class node_fare_service,node_airport_mapper,node_distance_calculator,node_distance_strategy,node_haversine_strategy,node_accurate_strategy,node_haversine_util,node_service_charge,node_fare_result,node_fare_breakdown toneRose
class node_fare_properties,node_charge_properties,node_error_handler,node_cache_config toneIndigo
```

## Components

### Airport data

- [Airport client](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/service/AirportClient.java): `aafe-fare-engine/src/main/java/com/aafe/fareengine/service/AirportClient.java`
- [Airports API](https://github.com/hbuz/aafe-airways/blob/main/airports-api/src/index.ts): `airports-api/src/index.ts`
- [Airport data model](https://github.com/hbuz/aafe-airways/blob/main/airports-api/src/model.ts): `airports-api/src/model.ts`

### Fare API

- [Itinerary endpoint](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/controller/ItineraryController.java): `aafe-fare-engine/src/main/java/com/aafe/fareengine/controller/ItineraryController.java`
- [Admin endpoint](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/controller/AdminController.java): `aafe-fare-engine/src/main/java/com/aafe/fareengine/controller/AdminController.java`

### Itinerary rules

- [Itinerary validation](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/validation/ItineraryValidator.java): `aafe-fare-engine/src/main/java/com/aafe/fareengine/validation/ItineraryValidator.java`
- [Validation annotation](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/validation/ValidItinerary.java): `aafe-fare-engine/src/main/java/com/aafe/fareengine/validation/ValidItinerary.java`
- [Station registry](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/service/StationRegistryService.java): `aafe-fare-engine/src/main/java/com/aafe/fareengine/service/StationRegistryService.java`

### Fare calculation

- [Fare orchestrator](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/service/FareCalculationService.java): `aafe-fare-engine/src/main/java/com/aafe/fareengine/service/FareCalculationService.java`
- [Airport coordinate mapper](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/mapper/AirportMapper.java): `aafe-fare-engine/src/main/java/com/aafe/fareengine/mapper/AirportMapper.java`
- [Distance selector](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/service/DistanceCalculator.java): `aafe-fare-engine/src/main/java/com/aafe/fareengine/service/DistanceCalculator.java`
- [Distance strategy contract](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/service/distance/DistanceStrategy.java): `aafe-fare-engine/src/main/java/com/aafe/fareengine/service/distance/DistanceStrategy.java`
- [Haversine strategy](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/service/distance/HaversineDistanceStrategy.java): `aafe-fare-engine/src/main/java/com/aafe/fareengine/service/distance/HaversineDistanceStrategy.java`
- [Geodesic strategy](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/service/distance/AccurateDistanceStrategy.java): `aafe-fare-engine/src/main/java/com/aafe/fareengine/service/distance/AccurateDistanceStrategy.java`
- [Haversine calculation](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/util/HaversineUtil.java): `aafe-fare-engine/src/main/java/com/aafe/fareengine/util/HaversineUtil.java`
- [Service charges](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/service/ServiceChargeCalculator.java): `aafe-fare-engine/src/main/java/com/aafe/fareengine/service/ServiceChargeCalculator.java`
- [Fare result](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/model/Itinerary.java): `aafe-fare-engine/src/main/java/com/aafe/fareengine/model/Itinerary.java`
- [Fare breakdown](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/model/FareBreakdown.java): `aafe-fare-engine/src/main/java/com/aafe/fareengine/model/FareBreakdown.java`

### Configuration and errors

- [Fare rules](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/config/FareEngineProperties.java): `aafe-fare-engine/src/main/java/com/aafe/fareengine/config/FareEngineProperties.java`
- [Charge rules](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/config/ServiceChargeProperties.java): `aafe-fare-engine/src/main/java/com/aafe/fareengine/config/ServiceChargeProperties.java`
- [API error mapping](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/exception/GlobalExceptionHandler.java): `aafe-fare-engine/src/main/java/com/aafe/fareengine/exception/GlobalExceptionHandler.java`
- [Cache configuration](https://github.com/hbuz/aafe-airways/blob/main/aafe-fare-engine/src/main/java/com/aafe/fareengine/config/CacheConfig.java): `aafe-fare-engine/src/main/java/com/aafe/fareengine/config/CacheConfig.java`

### Other components

- **API caller**

## Connections

- API caller → Itinerary endpoint: requests fare
- Itinerary endpoint → Validation annotation: validates input (evidence: `aafe-fare-engine/src/main/java/com/aafe/fareengine/controller/ItineraryController.java`)
- Validation annotation → Itinerary validation: delegates validation (evidence: `aafe-fare-engine/src/main/java/com/aafe/fareengine/validation/ValidItinerary.java`)
- Itinerary validation → Station registry: checks stations (evidence: `aafe-fare-engine/src/main/java/com/aafe/fareengine/validation/ItineraryValidator.java`)
- Itinerary validation → Fare rules: reads restrictions (evidence: `aafe-fare-engine/src/main/java/com/aafe/fareengine/validation/ItineraryValidator.java`)
- Itinerary endpoint → Fare orchestrator: calculates fare (evidence: `aafe-fare-engine/src/main/java/com/aafe/fareengine/controller/ItineraryController.java`)
- Fare orchestrator → Airport client: fetches airport data (evidence: `aafe-fare-engine/src/main/java/com/aafe/fareengine/service/FareCalculationService.java`)
- Airport client → Airports API: requests airport details (evidence: `aafe-fare-engine/src/main/java/com/aafe/fareengine/service/AirportClient.java`)
- Airports API → Airport data model: uses data model (evidence: `airports-api/src/index.ts`)
- Fare orchestrator → Airport coordinate mapper: maps coordinates (evidence: `aafe-fare-engine/src/main/java/com/aafe/fareengine/service/FareCalculationService.java`)
- Fare orchestrator → Distance selector: calculates leg distance (evidence: `aafe-fare-engine/src/main/java/com/aafe/fareengine/service/FareCalculationService.java`)
- Fare orchestrator → Fare rules: reads pricing rules (evidence: `aafe-fare-engine/src/main/java/com/aafe/fareengine/service/FareCalculationService.java`)
- Distance selector → Distance strategy contract: selects strategy (evidence: `aafe-fare-engine/src/main/java/com/aafe/fareengine/service/DistanceCalculator.java`)
- Haversine strategy → Haversine calculation: uses formula (evidence: `aafe-fare-engine/src/main/java/com/aafe/fareengine/service/distance/HaversineDistanceStrategy.java`)
- Fare orchestrator → Service charges: calculates charges (evidence: `aafe-fare-engine/src/main/java/com/aafe/fareengine/service/FareCalculationService.java`)
- Service charges → Charge rules: reads charge rules (evidence: `aafe-fare-engine/src/main/java/com/aafe/fareengine/service/ServiceChargeCalculator.java`)
- Fare orchestrator → Fare breakdown: builds breakdown (evidence: `aafe-fare-engine/src/main/java/com/aafe/fareengine/service/FareCalculationService.java`)
- Fare orchestrator → Fare result: returns itinerary (evidence: `aafe-fare-engine/src/main/java/com/aafe/fareengine/service/FareCalculationService.java`)
- API caller → Admin endpoint: requests refresh
- Admin endpoint → Station registry: refreshes stations (evidence: `aafe-fare-engine/src/main/java/com/aafe/fareengine/controller/AdminController.java`)
- Cache configuration → Airport client: caches responses
- API error mapping → API caller: returns API errors
