Skip to main content

​
Sourcing Architecture

Switchyard uses a multi-channel sourcing model that combines warehouse inventory, retail sweeps, and partner brand consignment to fulfill customer orders.

​
Sourcing Channels

ChannelDescriptionLead TimeTypical Use
RFC InventoryPre-stocked items in our fulfillment centerMinutesHigh-velocity items, perishables
Retail SweepsShopping trips to partner retailers1-4 hoursLong-tail catalog, price arbitrage
Partner ConsignmentInventory owned by partner brandsPre-stockedEmerging brands, specialty products

​
RFC Inventory

​
Overview

The RFC (Rapid Fulfillment Center) is our warehouse where we pre-stock high-velocity and perishable items for immediate fulfillment.

​
Inventory Structure

inventory_groups (hierarchical)
├── Zone (A=Ambient, C=Chilled, F=Frozen)
│   ├── Aisle
│   │   ├── Bay
│   │   │   ├── Shelf
│   │   │   │   └── Slot → inventory_locations → inventory_items

​
Picking Strategy

FEFO/FIFO (First Expiring First Out / First In First Out):
  1. Items with earliest expiration date picked first
  2. For non-perishables, oldest received date picked first
  3. Reserved quantities tracked to prevent over-allocation

​
Key Tables

TablePurpose
inventory_itemsPhysical stock with quantities, expiration, lot numbers
inventory_locationsWhere items are stored
inventory_groupsHierarchical warehouse organization
pick_listsPicking assignments for staff
pick_list_itemsIndividual items to pick

​
Retail Sweeps

​
Overview

Sweeps are shopping trips to partner retailers (HEB, Target, Walmart, Central Market, Whole Foods, Costco, Trader Joe’s) to source items not stocked in the RFC.

​
Sweep Economics

The system optimizes sweeps based on profitability:
SettingDescription
in_store_breakeven_itemsMinimum items for profitable in-store sweep
curbside_breakeven_itemsMinimum items for profitable curbside sweep
labor_rate_hourlyCost of driver time
new_sweep_marginal_costCost to add another sweep

​
Sweep Optimization

The Sweep Optimizer consolidates under-threshold sweeps:
  1. Identifies sweeps below breakeven threshold
  2. Finds alternative sweeps at same location with capacity
  3. Moves items to maximize efficiency
  4. Cancels empty sweeps

​
Sweep Flow

​
Key Tables

TablePurpose
routesGroups multiple sweeps for a driver trip
sweepsIndividual shopping trip to a retailer
sweep_itemsItems on the sweep manifest
sweep_order_allocationsLinks sweep items to customer orders
sweep_economics_settingsProfitability thresholds
retailer_mappingsAisle locations at each retailer
retailer_pricingOur acquisition cost at each retailer

​
Partner Brand Consignment

​
Overview

Partner brands ship their own products to our RFC for consignment sale. We handle fulfillment and take a commission on sales.

​
Partner Lifecycle

​
Commission Model

Temperature ZoneDefault Commission
Ambient15%
Chilled/Frozen20%
Commission can be overridden at the product level via sellable_products.commission_rate.

​
Manifest Flow

Partner manifests use TYPE 27 taxonomy IDs for QR code scanning:
  1. Admin creates reorder request with items and quantities
  2. Partner has 7 days to accept/reject
  3. On acceptance, manifest auto-created with QR code
  4. Partner ships to RFC with tracking info
  5. Staff scans manifest QR at receiving
  6. Items scanned into consignment inventory

​
Consignment Sales Tracking

When consignment inventory is sold:
  1. record_consignment_sale() function triggered
  2. Captures commission rate at time of sale
  3. Records commission_amount and net_to_partner
  4. Assigns to payout_period (YYYY-MM format)
  5. Partner views via portal, admin settles monthly

​
Shopify Integration

Partners can sync products from their Shopify store:
FeatureDescription
ImportInitial product import from Shopify catalog
Field SyncConfigurable per-field sync (name, price, images, etc.)
Daily CronAutomatic sync at 6am CST
Conflict HandlingLocal edits pause sync for that field
Audit LogsAll sync changes logged

​
Key Tables

TablePurpose
partner_brandsPartner company profiles and commission rates
partner_manifestsShipments from partners
partner_manifest_itemsLine items with expected/received quantities
partner_reorder_requestsAdmin-initiated inventory requests
partner_reorder_request_itemsRequest line items
consignment_salesSales records for payout calculation
shopify_syncPer-product sync configuration
shopify_sync_logsSync execution audit trail

​
Partner-Specific Fields

On scraped_products:
  • partner_brand_id - Links product to partner
On sellable_products:
  • is_partner_brand - Flag for partner products
  • commission_rate - Product-level commission override
On inventory_items:
  • partner_brand_id - Tracks consignment ownership
  • is_consignment - Flags consignment inventory
  • manifest_item_id - Links to receiving manifest

​
Allocation Engine

​
Decision Flow

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

​
Sourcing Priority

  1. RFC Inventory - Check available stock (FEFO/FIFO)
  2. Best Retailer - Compare prices across retailers
  3. Bulk vs Individual - Consider bulk SKU breakdowns
  4. Route Optimization - Prefer existing routes when possible

​
Key Functions

FunctionLocationPurpose
allocateOrder()order-allocation.tsMain allocation logic
runSweepOptimization()sweep-optimizer.tsPost-allocation optimization
findBestSweepForProduct()MeilisearchSweep selection by price/availability

​
Database Views

Prebuilt views for common queries:
ViewPurpose
partner_inventory_summaryActive consignment inventory by partner/product
partner_sales_by_periodSales aggregation with payout tracking
partner_pending_payoutsCurrent amounts due to partners
partner_manifests_summaryManifest status with receive percentages
partner_reorder_requests_summaryRequest status with expiry countdown
partner_products_viewProducts with partner brand context

​
Background Jobs

​
Scraper Scheduling

Retailer scrapers run on pg_cron schedules:
  • Updates retailer_pricing with current costs
  • Updates retailer_mappings with availability
  • Wakes scraper workers via pg_net HTTP calls

​
Shopify Sync

Daily sync at 6am CST via pg_cron:
  • Triggers trigger_shopify_sync() function
  • Calls internal API endpoint
  • Updates products based on sync configuration

​
Reorder Request Expiry

Requests expire after 7 days:
  • expire_old_reorder_requests() function
  • Marks status as expired
  • Partner notified of expiry

​
API Endpoints

​
Admin APIs

EndpointPurpose
POST /admin/ordersCreate orders
POST /admin/sweeps/optimizeRun sweep optimization
GET /admin/partners/brandsList partner brands
POST /admin/partners/brands/{id}/approveApprove partner
GET /admin/partners/manifestsList manifests
POST /admin/partners/reordersCreate reorder request

​
Partner Portal APIs

EndpointPurpose
GET /partner/productsView submitted products
GET /partner/manifestsView shipments
POST /partner/reorder-requests/{id}/acceptAccept reorder
GET /partner/salesView sales and payouts
POST /partner/shopify-importImport from Shopify

​
Scanner APIs

EndpointPurpose
GET /scanner/receiving/manifestsList pending manifests
POST /scanner/receiving/manifest/{id}/items/{itemId}/receiveRecord received item
GET /scanner/sweeps/{id}/itemsGet sweep shopping list

​
Integration Points

SystemIntegration
Goods Mobile AppOrder placement via API
Admin DashboardOrder management, partner admin
Partner PortalSelf-service partner management
Zebra ScannersPicking, receiving, sweep operations
ShopifyProduct import and sync
MeilisearchProduct search, sweep selection
pg_cronScheduled scraping and syncing