Swyft is an intelligent order routing and fulfillment optimization platform for Shopify merchants with multi-warehouse operations. We automatically route orders to the optimal warehouse based on inventory availability, geographic proximity, and configurable business rules.
┌─────────────────────────────────────────────────────────────────────────────┐
│ SHOPIFY ECOSYSTEM │
├─────────────────────────────────────────────────────────────────────────────┤
│ Shopify Store ←→ Webhooks ←→ Swyft Shopify App (React Router 7) │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ SWYFT PLATFORM │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Shopify App │ │ Worker Service │ │ Supabase │ │
│ │ (React Router) │ │ (Cloudflare) │ │ (PostgreSQL) │ │
│ │ │ │ │ │ │ │
│ │ • Dashboard │ │ • Order Routing │ │ • Orders │ │
│ │ • Webhooks │ │ • Inventory Sync│ │ • Inventory │ │
│ │ • Settings │ │ • Warehouse Sync│ │ • Warehouses │ │
│ │ • Connections │ │ • Reports │ │ • Decisions │ │
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
│ │ │ ▲ │
│ └───────────────────────┴───────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ WMS INTEGRATIONS │
├─────────────────────────────────────────────────────────────────────────────┤
│ Trackstar Unified API │
│ │ │
│ ┌─────────────────────────┼─────────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ ShipBob │ │ DaVinci │ │ Other │ │
│ │ WMS │ │ WMS │ │ WMS │ │
│ └─────────┘ └─────────┘ └─────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
| Component | Technology | Purpose |
|---|---|---|
| Framework | React Router 7 (Remix) | Shopify app UI & server-side rendering |
| UI Library | Shopify Polaris | Shopify-native design system |
| Hosting | Shopify App Hosting | Managed deployment for Shopify apps |
| Auth | Shopify App Bridge | OAuth & session management |
| Component | Technology | Purpose |
|---|---|---|
| Background Jobs | Cloudflare Workers | Cron-based order routing, syncing |
| Database | Supabase (PostgreSQL) | Primary data store with RLS |
| WMS Integration | Trackstar API | Unified interface to 40+ WMS providers |
| Package Manager | pnpm + Turborepo | Monorepo dependency management |
| Component | Technology |
|---|---|
| Language | TypeScript (strict mode) |
| Build | Turborepo (monorepo) |
| Linting | ESLint + Prettier |
| Testing | Vitest |
| CI/CD | GitHub Actions |
swyft/
├── apps/
│ ├── shopify-app/ # React Router 7 Shopify embedded app
│ │ ├── app/
│ │ │ ├── routes/ # File-based routing
│ │ │ │ ├── app._index.tsx # Dashboard
│ │ │ │ ├── app.connections.tsx # WMS connections
│ │ │ │ ├── webhooks.orders.create.tsx # Order ingestion
│ │ │ │ └── webhooks.orders.updated.tsx # Order updates
│ │ │ └── services/ # Server-side business logic
│ │ └── extensions/ # Shopify theme extensions (future)
│ │
│ └── worker/ # Cloudflare Worker for background jobs
│ └── src/
│ ├── handlers/ # HTTP & cron handlers
│ └── services/ # Order routing, sync services
│
├── packages/
│ ├── database/ # Supabase types & queries
│ ├── routing-engine/ # Order routing algorithm
│ ├── trackstar-client/ # Trackstar API client
│ ├── forecasting/ # Demand forecasting (future)
│ └── shared/ # Shared utilities & constants
│
└── supabase/
└── migrations/ # Database schema migrations
Shopify Order Created
│
▼
┌─────────────────────────────┐
│ webhooks.orders.create.tsx │
│ 1. Validate HMAC signature │
│ 2. Get/create store record │
│ 3. Upsert to unified_orders│
│ 4. Check report trigger │
└─────────────────────────────┘
│
▼
unified_orders table
(status: unfulfilled)
┌─────────────────────────────┐
│ Cloudflare Worker Cron │
│ (*/5 * * * *) │
└─────────────────────────────┘
│
▼
┌─────────────────────────────┐
│ Order Router Service │
│ 1. Fetch unrouted orders │
│ 2. Get warehouses & inv │
│ 3. Check routing rules │
│ 4. Run scoring algorithm │
│ 5. Store decision │
│ 6. Update order │
└─────────────────────────────┘
│
▼
┌─────────────────────────────┐
│ Routing Engine Algorithm │
│ │
│ Weights: │
│ • Inventory: 40% │
│ • Proximity: 35% │
│ • Cost: 15% │
│ • Capacity: 10% │
└─────────────────────────────┘
│
▼
routing_decisions table
unified_orders.routed_to_warehouse_id
┌─────────────────────────────┐
│ Warehouse Sync (Hourly) │
│ 1. Get active connections │
│ 2. Call Trackstar API │
│ 3. Upsert warehouses │
└─────────────────────────────┘
┌─────────────────────────────┐
│ Inventory Sync (15 min) │
│ 1. Get active connections │
│ 2. Call Trackstar API │
│ 3. Upsert inventory │
│ 4. Mark stale items │
└─────────────────────────────┘
| Table | Purpose |
|---|---|
stores |
Merchant accounts (shop domain, settings) |
sessions |
Shopify OAuth sessions |
sales_channels |
Shopify, Amazon, etc. per store |
unified_orders |
All orders from all channels |
unified_products |
Product catalog from Shopify |
fulfillment_locations |
Shopify Locations for native routing |
shopify_inventory |
Shopify inventory levels (native routing) |
trackstar_connections |
WMS connection credentials |
trackstar_warehouses |
Warehouse locations & metadata |
trackstar_inventory |
SKU-level inventory per warehouse |
routing_decisions |
Audit log of routing decisions |
routing_rules |
SKU-to-warehouse mapping rules |
feature_flags |
Per-store feature toggles |
stores (1) ──────< (N) unified_orders
stores (1) ──────< (N) trackstar_connections
trackstar_connections (1) ──────< (N) trackstar_warehouses
trackstar_warehouses (1) ──────< (N) trackstar_inventory
unified_orders (1) ──────< (1) routing_decisions
See Also:
docs/swyft/ROUTING-ARCHITECTURE.mdfor comprehensive routing documentation.
Swyft supports two independent routing approaches:
Routes orders by moving Shopify Fulfillment Orders to different Shopify Locations.
Order Webhook → Hold Order → Select Location → Move Fulfillment Order → Release Hold
Key Components:
fulfillment_locations table - Shopify Locations for routingshopify-routing-pipeline.ts → routeShopifyNativeOrders()shopify_native_routingSelection Logic:
Routes orders to WMS warehouses using Trackstar's unified API.
totalScore =
(inventoryScore × 0.40) + // Can fulfill all SKUs?
(proximityScore × 0.35) + // Distance to customer
(costScore × 0.15) + // Shipping zone estimate
(capacityScore × 0.10) // Warehouse priority
Key Components:
trackstar_warehouses + trackstar_inventory tablesorder-router.ts → routeOrders()Merchants can configure SKU-to-warehouse rules (Trackstar path only):
| Rule Type | Example | Use Case |
|---|---|---|
sku_affinity |
SKUs ABC-001, ABC-002 → Warehouse A |
Specific products |
sku_pattern |
SKUs matching OLD-% → Warehouse B |
Legacy inventory |
default |
All other orders → Warehouse C | Fallback |
Rules are evaluated by priority (highest first) before standard scoring.
Trackstar provides a unified API to 40+ WMS providers, eliminating the need to build individual integrations.
| Operation | Endpoint | Purpose |
|---|---|---|
| List Warehouses | GET /wms/warehouses |
Sync warehouse locations |
| List Inventory | GET /wms/inventory |
Sync stock levels |
| Create Order | POST /wms/orders |
Send routed orders to WMS |
| Get Order Status | GET /wms/orders/:id |
Track fulfillment |
1. Merchant clicks "Connect WMS" in Swyft
2. We create a Trackstar Link Token
3. Merchant completes OAuth in Trackstar modal
4. We exchange auth code for access token
5. Access token stored in trackstar_connections with integrationName (e.g., "shipbob")
6. Trackstar triggers historical data sync (30-day lookback)
7. Webhook: connection.historical-sync-completed received
8. We sync all warehouses to trackstar_warehouses
9. We sync all inventory to trackstar_inventory
10. We sync Shopify products to WMS (via Trackstar products.create)
Note: This flow is only required for Trackstar-based routing. Shopify-native routing does not require WMS connection.
┌─────────────────────────────────────────────────────────────────────────────┐
│ WMS ONBOARDING FLOW │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. App Install │
│ ├── Store created in stores table │
│ ├── Primary Shopify sales channel created (channel_type: 'shopify') │
│ └── Shopify products backfilled to unified_products (via direct API) │
│ │
│ 2. WMS Connection (via Trackstar Link) │
│ ├── User clicks "Connect WMS" → Trackstar modal opens │
│ ├── OAuth flow with WMS provider (ShipBob, ShipHero, etc.) │
│ ├── Exchange auth code → access_token + integrationName │
│ └── Store connection with display_name = integrationName (e.g. "shipbob")│
│ │
│ 3. Historical Sync (Trackstar-initiated) │
│ ├── Trackstar pulls 30 days of data from WMS │
│ └── Sends webhook: connection.historical-sync-completed │
│ │
│ 4. Swyft Sync (webhook-triggered) │
│ ├── Sync warehouses: trackstar.wms.warehouses.list() → DB │
│ ├── Sync inventory: trackstar.wms.inventory.listRaw() → DB │
│ └── Sync products: Shopify → WMS via trackstar.wms.products.create() │
│ │
│ 5. Bidirectional Inventory Sync (ongoing) │
│ ├── WMS → Swyft: inventory.updated webhook → trackstar_inventory │
│ └── Swyft → Shopify: Update Shopify inventory via Admin API (FREE) │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
| Channel | API Access | Cost | Use For |
|---|---|---|---|
| Shopify | Direct Admin API | FREE | Products, orders, inventory (primary store) |
| WooCommerce | Trackstar Cart API | $100/month | Additional sales channels |
| WMS | Trackstar WMS API | $100/connection | ShipBob, ShipHero, Extensiv, etc. |
Key Insight: Since Swyft is a Shopify app, we have direct API access to Shopify. We should NOT use Trackstar for Shopify operations - that would cost $100/month unnecessarily. Trackstar is only for WMS connections and non-Shopify sales channels.
| Operation | Endpoint | Purpose |
|---|---|---|
| List Warehouses | GET /wms/warehouses |
Sync warehouse locations |
| List Inventory | GET /wms/inventory |
Sync stock levels |
| List Products | GET /wms/products |
Get existing WMS products |
| Create Product | POST /wms/products |
Sync Shopify products to WMS |
| Create Order | POST /wms/orders |
Send routed orders to WMS |
| Get Order Status | GET /wms/orders/:id |
Track fulfillment |
| Metric | Capacity |
|---|---|
| Orders/minute | ~500 (webhook processing) |
| Routing batch | 50 orders per cron cycle |
| Inventory sync | 100 items per page, paginated |
| Bottleneck | Mitigation |
|---|---|
| Webhook throughput | Shopify handles queuing; we process async |
| Routing latency | Batch processing every 5 min |
| Inventory freshness | 15-minute sync; manual refresh available |
| Database connections | Supabase connection pooling |
# Deployed via Shopify CLI
pnpm shopify app deploy
Hosted on Shopify's managed infrastructure.
# Deploy to Cloudflare
cd apps/worker
pnpm deploy
# Push migrations to Supabase
supabase db push
| Variable | Purpose |
|---|---|
SHOPIFY_API_KEY |
App API key |
SHOPIFY_API_SECRET |
App secret |
SUPABASE_URL |
Database URL |
SUPABASE_SERVICE_ROLE_KEY |
Database admin key |
TRACKSTAR_API_KEY |
Trackstar API key |
| Variable | Purpose |
|---|---|
SUPABASE_URL |
Database URL |
SUPABASE_SERVICE_ROLE_KEY |
Database admin key |
TRACKSTAR_API_KEY |
Trackstar API key |
| Method | Endpoint | Purpose |
|---|---|---|
GET |
/health |
Health check |
POST |
/route-orders |
Manual routing trigger |
POST |
/sync-warehouses |
Manual warehouse sync |
POST |
/sync-inventory |
Manual inventory sync |
POST |
/process |
Process pending reports |
| Topic | Handler | Purpose |
|---|---|---|
orders/create |
webhooks.orders.create.tsx |
Ingest new orders |
orders/updated |
webhooks.orders.updated.tsx |
Sync order changes |
app/uninstalled |
webhooks.app.uninstalled.tsx |
Cleanup on uninstall |
| Limitation | Impact | Plan |
|---|---|---|
| No real-time routing | ~5 min delay from order to route | Cloudflare Queues |
| No split shipments | Can't split order across warehouses | Future feature |
| US-only geocoding | Limited international support | Add international data |
| No carrier rate shopping | Cost score is estimated | Integrate EasyPost |
Feel free to ask about any component, and we can dive deeper into the implementation details.