The Orchestrator

What This Does

This is the big boss function — processOrder(). At 1,040 lines, it's the largest file in the codebase. It coordinates the entire pipeline: claims the order, loads the shop config, fetches from Shopify, fetches from ShipStation, calculates corrections, routes to review or auto-push, pushes to ShipStation, verifies, and saves results. Every other module serves this one.

Why It Matters

This is where everything comes together. If you understand this file, you understand the entire pipeline. Every decision — skip, fail, review, push — happens here. It orchestrates calls to Shopify, ShipStation, the discount calculator, the verifier, billing, and email notifications.

How It Works

1. 1.STEP 1: Find the ProcessedOrder record in the database. If it doesn't exist, fail immediately.
2. 2.STEP 2: If the 'approved' flag is set (from review queue), skip to the push step using saved calculation data.
3. 3.STEP 3: Optimistic lock — atomically update status from PENDING to CALCULATING. If another worker already claimed it, bail out.
4. 4.STEP 4: Load shop config. Check ShipStation credentials exist.
5. 5.STEP 5: Get Shopify admin API access and fetch the full order details via GraphQL.
6. 6.STEP 6: Verify the order is international and has order-level discounts (double-check from webhook).
7. 7.STEP 7: Check billing limits. If plan limit reached, fail with BILLING error and send email.
8. 8.STEP 8: Decrypt ShipStation credentials and fetch the SS order. If not imported yet, set WAITING_ON_SHIPSTATION and retry later.
9. 9.STEP 9: Compare existing customs totals — if already correct, skip (idempotency).
10. 10.STEP 10: Calculate the discount ratio and apply to customs items.
11. 11.STEP 11: Route decision — if price discrepancy OR review mode, send to review queue. Otherwise, auto-push.
12. 12.STEP 12: Push corrected values to ShipStation API.
13. 13.STEP 13: Verify by reading customs back from ShipStation.
14. 14.STEP 14: Save all results (totals, reduction, verification status) and mark COMPLETED.

Key Decisions

• ●The optimistic lock (updateMany with status filter) prevents two workers from processing the same order simultaneously — no database-level locking needed.
• ●Billing check happens BEFORE the push (read-only), but the usage counter is incremented AFTER the push succeeds. This prevents counting orders that failed to push.
• ●The 1-hour timeout for ShipStation import gives plenty of time for auto-sync. After that, it's marked FAILED with a clear error message.
• ●Price discrepancy takes precedence over processing mode for routing to review — even in AUTO mode, discrepant orders need human review.

What Could Go Wrong

• ●ShipStation takes 5-15+ minutes to import new orders from Shopify. The WAITING_ON_SHIPSTATION status handles this gracefully with retries.
• ●If ShipStation's API is down during the push, the error is classified as TRANSIENT and the worker will retry via SQS.
• ●If the Shopify session has expired, the app can't fetch order data — this is a PERMANENT error requiring the merchant to re-authenticate.