rface RoutingConfig { weights: { proximity: number; cost: number; speed: number; reliability: number }; constraints: { maxSplits: number; excludedCarriers: string[]; fallbackNode: string }; }

class FulfillmentRouter { constructor(private config: RoutingConfig) {}

async compute(order: OrderConfirmedEvent) { const context = await resolveRoutingContext(order); const candidates = context.inventoryNodes.filter(node => this.hasCompleteStock(node, order.lineItems) && !this.config.constraints.excludedCarriers.includes(node.preferredCarrier) );

if (candidates.length === 0) {
  return this.applyFallback(order, context);
}

const scored = candidates.map(node => ({
  node,
  score: this.calculateScore(node, context, order)
}));

scored.sort((a, b) => b.score - a.score);
return scored[0];

}

private calculateScore(node: InventoryNode, ctx: RoutingContext, order: OrderConfirmedEvent): number { const proximityScore = this.normalizeDistance(node, order.destination) * this.config.weights.proximity; const costScore = this.invertCarrierCost(ctx.carrierQuotes, node) * this.config.weights.cost; const speedScore = this.slaAlignment(ctx.slaConstraints, node) * this.config.weights.speed; const reliabilityScore = this.nodeReliabilityFactor(node, order.orderValue) * this.config.weights.reliability;

return proximityScore + costScore + speedScore + reliabilityScore;

} }

### Architecture Decisions & Rationale
1. **Event-Driven Trigger**: Eliminates polling overhead and guarantees routing occurs at the exact moment financial authorization completes. This prevents race conditions where inventory changes between order creation and routing.
2. **Parallel Data Fetching**: Carrier APIs and inventory systems have independent latency profiles. `Promise.all` ensures the routing decision waits only for the slowest dependency, not the sum of all dependencies.
3. **Scoring Matrix over Conditional Logic**: Hardcoded routing rules require code deployments for every business change. A weighted scoring system allows merchants to adjust priorities via configuration without touching the codebase.
4. **Deterministic Fallback**: When primary nodes fail capacity checks or stock validation, the engine must have a predefined fallback topology. This prevents order deadlocks and ensures continuous throughput.
5. **Stateless Computation**: The routing engine holds no persistent state. It receives a snapshot, computes, and returns an assignment. This enables horizontal scaling and simplifies debugging.

## Pitfall Guide

### 1. Sequential API Resolution
**Explanation**: Fetching inventory, carrier rates, and capacity checks one after another multiplies latency. At scale, this pushes routing decisions past acceptable thresholds, delaying fulfillment queue ingestion.
**Fix**: Resolve all external dependencies in parallel. Implement timeout boundaries and degrade gracefully if a non-critical service (e.g., secondary carrier) fails.

### 2. Cached Inventory Assumptions
**Explanation**: Relying on stale inventory counts leads to overselling and forced order splits. A node may show 10 units in cache but have 0 after concurrent checkout events.
**Fix**: Use optimistic concurrency with reservation locks. The routing engine should request a temporary hold on inventory during scoring. If the hold fails, the node is disqualified and the engine re-evaluates.

### 3. Hardcoded Carrier Preferences
**Explanation**: Assigning orders to a default carrier ignores dimensional weight, zone pricing, and service-level dynamics. A carrier that's cheapest for Zone 2 may be 40% more expensive for Zone 8.
**Fix**: Implement live rate shopping. Query multiple carriers for the exact weight/dimension/destination combination and select the optimal quote at routing time.

### 4. Missing Fallback Topology
**Explanation**: When the highest-scoring node is at capacity or experiences a system outage, orders stall in a pending state. Manual intervention becomes necessary, breaking automation.
**Fix**: Define a deterministic fallback chain with capacity thresholds. The engine should automatically cascade to the next viable node without human input, logging the deviation for audit.

### 5. Ignoring Split-Order Economics
**Explanation**: Treating order splits as a neutral or positive outcome ignores packaging duplication, increased transit variance, and customer confusion. Splits should only occur when explicitly permitted.
**Fix**: Apply a heavy penalty to the scoring matrix when a node cannot fulfill all line items. Only allow splits if `maxSplits > 0` and the cost delta remains within merchant-defined thresholds.

### 6. No Decision Auditability
**Explanation**: Without logging the routing context, scores, and final assignment, debugging SLA breaches or margin leaks becomes impossible. Engineers cannot optimize what they cannot observe.
**Fix**: Persist a routing audit record containing the input snapshot, normalized scores, selected node, and fallback triggers. Store this in a time-series database for trend analysis and rule tuning.

### 7. Rule Engine Coupling
**Explanation**: Embedding business logic directly into the routing codebase creates deployment bottlenecks. Every priority change (e.g., "favor speed over cost during holidays") requires a code release.
**Fix**: Externalize routing rules to a configuration layer. Use a lightweight DSL or JSON schema that the scoring engine evaluates at runtime. Version control the configuration independently of the application code.

## Production Bundle

### Action Checklist
- [ ] Replace static location assignment with an event-driven routing trigger on order confirmation
- [ ] Implement parallel data resolution for inventory, carrier rates, and node capacity
- [ ] Design a weighted scoring matrix instead of conditional routing branches
- [ ] Add temporary inventory reservation locks to prevent overselling during evaluation
- [ ] Define a deterministic fallback topology with capacity thresholds
- [ ] Penalize order splits in the scoring algorithm unless explicitly permitted
- [ ] Persist routing audit logs with input context, scores, and assignment rationale
- [ ] Externalize routing rules to a configuration layer for runtime tuning

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Single warehouse, single carrier | Static assignment with manual override | Complexity outweighs benefit at low volume | Baseline |
| Multi-node, <100 orders/day | Event-driven routing with simplified scoring | Reduces manual triage without over-engineering | -5–8% carrier costs |
| Multi-node, 100–500 orders/day | Full scoring matrix with live rate shopping | Eliminates split inflation and zone pricing mismatches | -12–18% carrier costs, -40% manual overhead |
| Enterprise multichannel (FBA/3PL/Owned) | Deterministic routing with fallback topology & audit trail | Handles capacity constraints, SLA commitments, and margin optimization at scale | -15–22% carrier costs, +6–10% retention via SLA compliance |

### Configuration Template

```yaml
# routing-config.yaml
version: 2.1
merchant_id: m_8842
scoring_weights:
  proximity: 0.25
  cost: 0.35
  speed: 0.25
  reliability: 0.15
constraints:
  max_splits: 0
  excluded_carriers:
    - "carrier_legacy_economy"
    - "carrier_regional_slow"
  fallback_topology:
    - node_id: "wh_east_primary"
      capacity_threshold: 0.85
    - node_id: "3pl_central_backup"
      capacity_threshold: 0.90
    - node_id: "fba_auto_assign"
      capacity_threshold: 1.0
sla_profiles:
  standard:
    max_transit_days: 5
    penalty_for_breach: 0.4
  express:
    max_transit_days: 2
    penalty_for_breach: 0.7
  overnight:
    max_transit_days: 1
    penalty_for_breach: 0.9
audit:
  enabled: true
  retention_days: 90
  storage: "timeseries_db"

Quick Start Guide

1. Initialize the event listener: Hook into your commerce platform's order confirmation webhook or message queue. Map the payload to the OrderConfirmedEvent interface and emit it to the routing stream.
2. Deploy the scoring engine: Containerize the FulfillmentRouter class. Configure the scoring weights and constraints using the YAML template. Ensure the engine is stateless and horizontally scalable.
3. Connect data providers: Implement adapters for your inventory management system, carrier rate APIs, and capacity monitoring service. Enforce parallel resolution with timeout boundaries (e.g., 200ms max per provider).
4. Validate with shadow routing: Run the engine in shadow mode for 7–14 days. Log routing decisions without executing assignments. Compare scoring outputs against historical manual assignments to calibrate weights.
5. Activate deterministic assignment: Switch from shadow mode to active routing. Monitor audit logs for fallback triggers and split penalties. Adjust configuration weights based on observed margin and SLA compliance metrics.

Deterministic fulfillment routing transforms order assignment from a reactive operational task into a predictable, margin-positive engineering system. By decoupling routing logic, enforcing parallel evaluation, and externalizing business rules, teams eliminate the hidden costs of manual triage and static defaults. The architecture scales linearly, adapts to carrier and inventory changes without code deployments, and provides full observability into every assignment decision. Implement it correctly, and the P&L impact becomes visible before customer support metrics ever reflect it.