Carrier Integration and Rate Normalization Engine Blueprint

Role: Staff API Platform Engineer specializing in logistics integrations, asynchronous distributed gateways, and schema normalization.

Context

• Target carrier protocol mix: {{carrier_protocols}}.
• Maximum allowable quotation timeout: {{quote_timeout_ms}}.
• Internal standard schema: {{canonical_schema_standard}}.
• Request deduplication and replay safety: {{idempotency_strategy}}.
• Cache invalidation interval: {{caching_ttl_seconds}}.
• Upstream failure tolerance budget: {{error_handling_budget}}.

Task

Architect a high-performance backend carrier integration framework that federates real-time rate shopping, normalizes disparate vendor payloads into {{canonical_schema_standard}}, and guarantees resilient transaction execution across unreliable carrier endpoints.

Method

1. Define the API Gateway mediation layer, including request dispatch, scatter-gather concurrency patterns, and dynamic timeout handling.
2. Design the translation and adapter pattern matrix converting vendor-specific payloads into {{canonical_schema_standard}}.
3. Formulate the concurrency and fan-out orchestrator ensuring aggregate responses return within {{quote_timeout_ms}} even if specific carriers hang.
4. Specify the caching and rate-invalidation framework enforcing {{caching_ttl_seconds}} while guarding against stale shipping tariffs.
5. Design the transactional booking workflow implementing {{idempotency_strategy}} to eliminate double-booking across distributed systems.
6. Structure the circuit breaker and fallback mechanisms aligned with {{error_handling_budget}} to handle degraded carrier APIs.
7. Detail distributed tracing, logging, and audit schemas for every outgoing carrier payload and normalized response.

Constraints

• MUST enforce strict scatter-gather cancellation to return available rates before {{quote_timeout_ms}} expires.
• MUST NOT allow non-idempotent booking requests to reach upstream carrier endpoints.
• Adapter modules must be fully isolated to permit adding new carrier protocols without modifying core orchestration logic.
• Error responses from third-party carriers must map cleanly to standardized internal error codes.

Output format

• Gateway Architecture & Concurrency Model: Workflow diagram and detailed description of the scatter-gather engine.
• Canonical Schema Mapping Specification: Data dictionary and mapping table showing source-to-canonical translation.
• Idempotency & Transaction State Machine: Step-by-step state transition table for quote, hold, and book actions.
• Resilience & Fallback Matrix: Rules for handling timeouts, 4xx/5xx carrier responses, and circuit transitions.
• Implementation Code Template: Production-grade backend interface/trait definitions in TypeScript or Go.

Self-review

• Verify that the scatter-gather pattern explicitly handles slow or unresponsive carrier endpoints.
• Confirm that {{canonical_schema_standard}} supports all structural variants present in {{carrier_protocols}}.
• Check that the idempotency mechanism prevents duplicate charges during intermittent network partitions.
• Ensure the five required output sections are distinctly separated and labeled.