Fulfillment Module Technical Specifications

The fulfillment engine is the central routing and inventory orchestration layer. It handles three primary concerns:

1. Geospatial warehouse selection — Haversine distance calculation to find nearest facilities
2. Atomic inventory movement — guarded atomic updates preventing overselling
3. Order allocation — Multi-SKU, multi-warehouse greedy allocation with split-order support

No external routing API required. All math is pure JavaScript using the Haversine formula.

1.1 Geospatial Warehouse Selection

For a given SKU and quantity, the engine pulls every active warehouse that has coordinates on file, checks live inventory for that SKU across all of them, and filters out any warehouse without enough sellable stock (on-hand minus what's already allocated to other orders). The remaining candidates are ranked nearest-first using the Haversine distance from the customer's location.

Returns all eligible warehouses sorted by distance, not just the best one. This lets the allocator implement fallback routing or split orders when one warehouse alone can't cover the order.

1.2 Greedy Multi-Warehouse Allocation

When an order comes in, the engine geocodes the shipping address if it doesn't already have coordinates, then walks each line item: it fetches the distance-ranked warehouse list for that SKU and allocates from the nearest warehouse first, moving to the next-nearest only if quantity remains unfulfilled. Each partial allocation is its own atomic, guarded stock movement, so a failure partway through never leaves inventory in an inconsistent state.

Split-order support: If Warehouse A has 3 units and the order needs 5, the engine allocates 3 from A, then 2 from B. Each allocation is atomic.

Events emitted: fulfillment.order_allocated (success) or fulfillment.allocation_failed (partial/full failure) — with the reason and any unfulfilled quantity included. Downstream modules (notifications, inventory dashboards) subscribe independently.

Every inventory change in the system — inbound receipt, allocation, outbound shipment, transfer, adjustment — goes through a single write path that enforces atomicity with a database-level guard clause, so the check ("is there enough stock?") and the update ("reserve it") happen as one indivisible operation.

2.1 Allocation — Guard Against Overselling

When an order allocates stock, the reserved quantity is incremented, but the update only commits if on-hand stock minus what's already reserved still covers the requested amount. If two concurrent orders both read "3 units available" and both try to allocate 3 units, the first succeeds and the second is rejected outright with an "insufficient stock" error — instead of both succeeding and driving the count to -3.

2.2 Outbound — Guard Against Negative Stock

The same pattern applies to outbound shipments: on-hand and reserved quantities are decremented together, but only if on-hand stock actually covers the quantity being shipped. Without this guard, an outbound movement could drive on-hand stock negative, making the inventory ledger meaningless.

2.3 Inventory Field Model

Each SKU-per-warehouse inventory record tracks:

• On-hand — physical units in the warehouse (increases on inbound, decreases on outbound)
• Allocated — reserved for pending orders (increases on allocation, decreases on outbound)
• Available — on-hand minus allocated (the sellable quantity)
• Reorder point — the threshold that triggers a low-stock alert

Low-stock event: Whenever available stock drops to or below the configured reorder point, a fulfillment.low_stock event fires with the SKU, warehouse, and remaining quantity — ready to wire into a purchase-order workflow.

2.4 Immutable Movement Ledger

Every stock movement — inbound, outbound, transfer, allocation, or adjustment — writes a new, immutable ledger entry recording the type, quantity, reason, and the user who triggered it. No updates, no deletes — only new entries. The ledger is the source of truth for inventory reconciliation and audit trail.

Distance calculation uses the Haversine formula — great-circle distance on a sphere, computed directly from each warehouse's latitude/longitude and the customer's, accounting for the Earth's curvature.

Why Haversine? More complex spatial-indexing schemes are over-engineered for warehouse routing. Haversine is:

• Pure math, no external API calls, no index required
• Accurate to <0.5% for most terrestrial distances
• Handles the curvature of the Earth without projection errors

Geocoding — no paid API required: When a customer address has no coordinates on file, Aeion resolves them through a free OpenStreetMap-based lookup by default. A paid geocoding provider (Google Maps, Mapbox) can be swapped in for brands that need higher-volume bulk geocoding, with no change to how routing itself works.

Fulfillment's data model covers:

• Warehouses — facility records with coordinates, capacity, and active/inactive status
• Inventory — per-SKU-per-warehouse stock levels: on-hand, allocated, available, and reorder point
• Movement ledger — an immutable record of every stock change, with type, reason, and the user who made it
• Shipments — carrier shipments with tracking numbers, labels, and manifests
• Fulfillments — order fulfillment records, linked back to their originating Commerce order
• Returns (RMA) — return authorizations with per-item condition tracking and restock flags
• Picking lists — batch pick lists aggregated across multiple orders
• Locations — bin/location codes within warehouses, shared with the Production module
• Shipping methods — carrier service levels with rate overrides

Warehouses own their bin/location records; inventory is tracked per SKU per warehouse; fulfillments link back to Commerce orders; returns and picking lists link back to their fulfillment records.