AircraftOps
Search
Documentation
Posts

FAA ↔ ICAO Linking Worker

Architecture → Serverless Functions

Serverless worker responsible for FAA aircraft registry to ICAO aircraft type linking. Processes SQS ingestion events, performs candidate filtering, verification-based LLM matching, and persists validated linking records into DynamoDB with idempotent execution guarantees.

Execution Flow
  1. SQS delivers FAA aircraft linking job messages.
  2. The Lambda handler extracts subject_id and aircraft metadata.
  3. An idempotency check determines whether a linking result already exists.
  4. If not cached, the worker filters ICAO variant candidates using a preloaded variant dataset.
  5. An LLM verification prompt validates the correct ICAO type using authoritative sources.
  6. The confirmed result is validated via a strict Pydantic schema.
  7. The final linking record is persisted to DynamoDB.
Lambda Handler

The entrypoint processes SQS batch events, parses each message, and invokes the job runner. Each message contains:

  • subject_id — aircraft identifier
  • metadata — make, model, serial, and FAA family code
  • force_refresh — optional cache bypass flag

The handler is intentionally stateless and relies on DynamoDB for persistence and deduplication.

Idempotency / Cache Check

Before executing the linking workflow, the system checks DynamoDB for an existing linking record using the composite key:

  • mfr_mdl_code
  • serial

If a record exists, the stored result is immediately returned, preventing duplicate LLM calls and reducing compute cost.

Linking Workflow

The linking engine combines deterministic candidate filtering with verification-based LLM inference.

Candidate Filtering

A local JSON dataset containing ICAO variant mappings is filtered using aircraft manufacturer and model metadata to generate a constrained candidate list. These candidates are provided to the LLM strictly as lookup hints.

Verification-Only LLM Matching

The system prompt enforces strict rules requiring independent verification from authoritative aviation sources. The model must:

  • Verify ICAO designators through trusted aviation databases
  • Reject unverifiable matches
  • Return output strictly conforming to the defined JSON schema
Schema Validation

LLM responses are validated using the FAAICAOLinkRequestModel Pydantic schema to ensure:

  • Strict JSON output compliance
  • Correct data typing
  • Guaranteed presence of required fields
DynamoDB Persistence

Successfully verified matches are written to DynamoDB using the FAAICAOLinkModel repository layer. Stored attributes include:

  • Manufacturer / model metadata
  • FAA manufacturer-model family code
  • Aircraft serial number
  • Confirmed ICAO type designator
  • Verification confidence score
Operational Characteristics
  • Idempotent job execution via existing-record detection
  • Cost-optimized LLM usage through candidate narrowing and schema-constrained output
  • Batch-safe processing compatible with SQS event delivery
  • Strict validation guarantees before persistence
  • Fully stateless Lambda design suitable for high-volume ingestion pipelines
← FAA Registry Synchronization Worker Typesense Indexing Worker →