The Quote API & Order Lifecycle

In This Component

Decision science is only valuable when it reaches production. This component covers how the DLA engine is wrapped in a production-grade FastAPI service — with correct idempotency, atomic persistence, and durable CRM event delivery.

The Quote Request Sequence

A single POST /quote request flows through six layers before returning:

1. Cloud Run IAM gate: Google identity token verified before the container is even reached
2. Firebase JWT verification: Authorization: Bearer <token> checked for issuer, signature, expiry, and project audience
3. Role authorization: signed roles custom claim must include "ops" or "analyst"
4. Idempotency check: Idempotency-Key header is looked up in quote_decisions — if found, the stored result is returned immediately without re-running the DLA engine
5. State snapshot read: current PoultryState loaded from current_state_snapshots table
6. DLA evaluation: DLAPolicyEngine.get_optimal_action() runs the full Monte Carlo evaluation
7. Atomic commit: DecisionRecord + OutboxEntry inserted in a single engine.begin() transaction — both or neither persist

The DecisionRecord

Every quote produces a fully auditable DecisionRecord frozen dataclass containing: decision and order UUIDs, all version vectors (model, policy, feature schema, configuration, state snapshot), all candidate actions considered, the selected action, expected margin, competitor price index at decision time, and decision latency in milliseconds.

The Transactional Outbox Pattern

Quote decisions are immediately written to an integration_outbox table alongside the decision record. An OutboxDispatcher then delivers these events to external CRM systems via HTTPS with exponential backoff, attempt counting, dead-lettering, and an Idempotency-Key header sent with every delivery attempt. This guarantees at-least-once delivery without distributed transactions.