> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchyard.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Order Flow

> Complete order lifecycle from placement to delivery

# Order Flow

This document describes the complete lifecycle of an order in the Goods/Switchyard system, from customer placement through robot delivery.

## Overview

Orders in Goods can be fulfilled from two sources:

1. **RFC (Warehouse)** - Items stocked in our fulfillment center, available for immediate picking
2. **Retailers** - Items sourced from partner retailers (HEB, Target, Walmart, Central Market, Whole Foods, Costco, Trader Joes)

The fulfillment strategy depends on product availability, pricing, and route optimization.

## Order Fulfillment Flow

```mermaid theme={null}
flowchart TD
    subgraph OrderPlacement [Order Placement]
        APP[Goods App] --> |Create Order| ORD[orders table]
        ADMIN[Admin Dashboard] --> |Manual Order| ORD
        ORD --> OI[order_items]
    end
    
    subgraph Allocation [Order Item Allocation]
        OI --> ALLOC{Allocation Engine}
        ALLOC --> |Check inventory| INV[(inventory_items)]
        INV --> |Sufficient stock?| PICK_PATH
        INV --> |Insufficient/None| SWEEP_PATH
    end
    
    subgraph PICK_PATH [RFC Fulfillment Path]
        PL[pick_lists<br/>Assigned to staff picker] --> PLI[pick_list_items]
        PLI --> |FEFO/FIFO select| INV
        PLI --> |Picker scans| PICKER[Picker with Zebra]
        PICKER --> |Scan item into| BAG_PICK[bag via bag_items]
    end
    
    subgraph SWEEP_PATH [Sweep Fulfillment Path]
        RETAILER_SELECT{Select Best Retailer}
        RETAILER_SELECT --> |Price + Availability| RT[routes]
        RT --> SW[sweeps<br/>Assigned to staff driver]
        SW --> SWI[sweep_items]
        SWI --> |Get aisle from| RM[(retailer_mappings)]
        SWI --> DRIVER[Driver Shops]
        DRIVER --> |Return to RFC| INTAKE[Intake Station]
        INTAKE --> |Scan items into| BAG_SWEEP[bag via bag_items]
    end
    
    subgraph Assembly [Order Assembly]
        BAG_PICK --> BAGS[bags]
        BAG_SWEEP --> BAGS
        BAGS --> |Assigned to| TOTES[totes]
        TOTES --> |Staged at| LOC[inventory_locations]
    end
    
    subgraph Delivery [Delivery]
        TOTES --> |Paired with| ROBOT[robots]
        ROBOT --> CUSTOMER[Customer Pickup]
    end
    
    ALLOC --> RETAILER_SELECT
```

## Bags, Totes, and Order Assembly

```mermaid theme={null}
flowchart TD
    subgraph OrderAssembly [Order Assembly Flow]
        OI[order_items] --> ALLOC{Allocation}
        
        ALLOC --> |From Inventory| PLI[pick_list_items]
        ALLOC --> |From Sweep| SWI[sweep_items]
        
        PLI --> |Picker scans into| BAG1[bags]
        SWI --> |Intake scans into| BAG2[bags]
        
        BAG1 --> |Assigned to| TOTE[totes]
        BAG2 --> |Assigned to| TOTE
        
        TOTE --> |Paired with| ROBOT[robots]
        ROBOT --> |Delivers to| CUSTOMER[Customer Pickup]
    end
```

### Relationships:

* **Order** → has many **Totes** (one order may require multiple totes)
* **Tote** → has many **Bags** (bags go inside totes)
* **Bag** → has many **Bag Items** (items packed into a bag)
* **Bag Item** → links to **Order Item** (fulfills an order item)
* **Tote** → paired with **Robot** for delivery (1:1)

### Bag Types

Bags are temperature-separated:

* **ambient** - Room temperature items
* **chilled** - Refrigerated items
* **frozen** - Frozen items

## Order Statuses

| Status              | Description                                     |
| ------------------- | ----------------------------------------------- |
| `pending`           | Order just placed, awaiting processing          |
| `processing`        | Being allocated to sweeps and/or RFC pick queue |
| `sweep_in_progress` | Driver is shopping at retailer(s)               |
| `intake`            | Items returned to RFC, being sorted             |
| `picking`           | RFC items being picked by warehouse staff       |
| `staged`            | Order assembled in tote, ready for robot        |
| `delivering`        | Robot en route to customer                      |
| `delivered`         | Customer has received order                     |

## Staff Roles

| Role       | Responsibilities                                   |
| ---------- | -------------------------------------------------- |
| **Picker** | Picks items from RFC inventory, scans into bags    |
| **Driver** | Performs sweeps at retailers, returns items to RFC |

<Note>
  Staff members can have both picker and driver roles, but cannot perform both simultaneously. Each pick\_list is assigned to a staff member with the picker role. Each sweep is assigned to a staff member with the driver role.
</Note>

## Detailed Flow

### 1. Order Placement

Customer places an order through the Goods mobile app or admin dashboard. Orders reference:

* **location\_id** - Store location for pricing and tax
* **customer\_id** - Customer placing the order
* **source** - 'app' or 'admin'

Order items reference **sellable\_products** (not raw scraped products).

### 2. Source Analysis (Allocation Engine)

When an order arrives, the allocation engine analyzes each line item:

**Decision Factors:**

* RFC inventory availability (using FEFO/FIFO)
* Retailer pricing (we track costs at each retailer)
* Bulk vs individual SKU pricing
* Route optimization

**Sourcing Rules:**

1. Check inventory\_items for available stock (FEFO/FIFO order)
2. If sufficient stock → allocate to pick\_list (fulfillment\_source = 'inventory')
3. If insufficient/none → allocate to sweep (fulfillment\_source = 'sweep')
4. For sweeps, select best retailer based on price (including bulk SKU options)

### 3. RFC-Only Orders (Inventory Path)

Orders containing only RFC-stocked items:

1. Order items allocated to pick\_list
2. Pick\_list assigned to staff (picker)
3. Picker uses Zebra scanner to locate items (FEFO/FIFO order)
4. Picker scans items into bags (temperature-separated)
5. Bags assigned to totes
6. Totes staged for robot delivery

### 4. Sweep Operations

Orders requiring retailer items:

**Routes and Sweeps:**

* Routes group multiple sweeps for a driver trip
* Each sweep is for one retailer store
* Sweep type: 'order' (for customer orders) or 'inventory' (for stock replenishment)

**Sweep Manifest:**

* Aggregates items from sweep\_items
* Includes aisle locations from retailer\_mappings
* Driver receives manifest on their device

**During Shopping:**

* Driver shops the manifest
* Records actual\_price paid
* If item is out of stock, can be pushed to another sweep or substituted

### 5. Intake Processing

When drivers return from sweeps:

1. Items scanned at intake station
2. Scanned items create bag\_items linked to:
   * sweep\_item\_id (for tracking)
   * order\_item\_id (for fulfillment)
3. Bags assigned to totes per order

### 6. Order Picking (RFC Items)

Pickers use Zebra scanners with the picking app:

1. Picker assigned to pick\_list
2. App guides picker to inventory items (FEFO/FIFO order)
3. pick\_list\_item.inventory\_item\_id tracks which specific item
4. Picker scans into bag, creates bag\_item
5. pick\_list\_item.bag\_item\_id links to the created bag\_item

### 7. Staging

Completed orders are staged in totes:

* Bags from both pick path and sweep path combined
* Each tote has a tote\_code (QR)
* Totes staged at inventory\_locations
* One robot assigned per tote (1:1)

### 8. Robot Delivery

1. Robot scans tote QR (tote\_code)
2. Robot delivers tote to customer location
3. Customer picks up order
4. Order marked as delivered

## Fulfillment Types

| Type       | Items From              | Fulfillment Time             |
| ---------- | ----------------------- | ---------------------------- |
| RFC-Only   | inventory\_items        | \~10 minutes                 |
| Sweep-Only | Retailer(s)             | Next available pickup window |
| Hybrid     | Inventory + Retailer(s) | Next available pickup window |

## Key Entities

| Entity            | Purpose                                          |
| ----------------- | ------------------------------------------------ |
| orders            | Customer order with line items                   |
| order\_items      | Line items referencing sellable\_products        |
| routes            | Groups multiple sweeps for a driver trip         |
| sweeps            | Shopping trip to a retailer                      |
| sweep\_items      | Item on a sweep manifest                         |
| pick\_lists       | RFC picking assignment for a picker              |
| pick\_list\_items | Item to pick from warehouse                      |
| staff             | Pickers and drivers (replaces old drivers table) |
| totes             | Container for robot delivery                     |
| bags              | Temperature-separated bags inside totes          |
| bag\_items        | Items packed into bags                           |

## Integration Points

| System            | Integration                                      |
| ----------------- | ------------------------------------------------ |
| Goods Mobile App  | Places orders via Switchyard API                 |
| Admin Dashboard   | Manual order creation, staff management          |
| Zebra Scanners    | Scanner API for picking and intake               |
| Robot System      | Reads tote\_code QR codes                        |
| Payment Providers | payment\_collection → payment\_session → payment |