ZenHQ

About This Project

ZenHQ is a full-stack e-commerce operations platform built for grocery and food delivery businesses. The system spans three interconnected applications: a multi-tenant operations dashboard for order management and fulfillment, a standalone checkout REST API with payment processing and delivery scheduling, and a React-based white-label checkout frontend with Paysafe 3D Secure integration.

We designed and built the entire ecosystem from the ground up. The platform integrates deeply with Shopify for product catalog and order sync, supports multiple payment gateways (Paysafe, PayPal, Payfirma), handles complex delivery logistics with GPS tracking and time-window scheduling, and manages batch pricing operations across multiple stores — all isolated through a robust multi-tenant architecture.

Platform Overview

Three-Application Architecture

ZenHQ is not a single app — it's an ecosystem of three purpose-built applications that work together:

• 
  ZenManage (Operations Dashboard) — A Rails backend managing orders, fulfillment, delivery tracking, employee shifts, batch pricing, and B2B customer accounts across multiple Shopify stores


• 
  Checkout REST API — A dedicated API handling the entire cart-to-order pipeline: cart management, address validation, delivery scheduling, discount codes, tax calculations, and payment processing


• 
  ZenPay (Checkout Frontend) — A React application providing a branded, multi-step checkout experience with Paysafe credit card processing, Google Maps delivery zone detection, and bilingual EN/FR support

Multi-Tenant Architecture

Every component uses the Apartment gem for database-level tenant isolation. Each tenant maps to a single Shopify store with its own:

• Shopify API credentials and webhook endpoints


• Payment gateway configuration (different Paysafe/PayPal accounts per store)


• Delivery zones, time windows, and fee structures


• Branding, colors, and frontend theme customization


• Tax rates and discount code pools


• Employee roles and access permissions

Shopify Integration

Deep, bidirectional Shopify integration powers the entire platform:

• Real-time webhook handlers for orders, products, customers, inventory, and transactions — keeping local data in sync


• Product and variant sync with local enrichment (batch pricing, aisle mapping, sorting groups)


• Order creation via Shopify REST API after successful payment in the custom checkout


• Customer lookup and free shipping flag management


• Fulfillment creation directly from the operations dashboard


• Embedded checkout mode that integrates into existing Shopify storefronts

Custom Checkout Flow

The checkout is a 4-step wizard built in React with Material-UI:

• 
  Step 1 — Customer Info: Name, email, phone with validation, address autocomplete via Google Places API


• 
  Step 2 — Delivery Scheduling: Calendar date picker, time window selection, store pickup with Google Maps, delivery zone auto-detection via geolocation


• 
  Step 3 — Payment: Paysafe hosted fields (PCI compliant), 3D Secure v2 authentication, saved card management, PayPal Express, on-delivery payment option


• 
  Step 4 — Confirmation: Order summary, fulfillment tracking, delivery details, continue shopping CTA

Payment Processing

Multi-gateway payment architecture via ActiveMerchant:

• Paysafe/Netbanx — Primary credit card gateway with card vault tokenization and 3D Secure v2


• PayPal Express Checkout — Alternative payment method


• Payfirma — Secondary card gateway for specific merchants


• On-delivery payment — Cash/card at door option


• Per-store gateway routing — each store can use different payment accounts


• Authorization vs. direct purchase logic based on customer history

Delivery & Logistics

Complex delivery management with multiple moving parts:

• Delivery zone mapping using GPS polygon detection (point-in-polygon via Geokit)


• Zip code prefix fallback for zone assignment


• Time window capacity management with automatic slot closing when full


• Same-day delivery surcharge calculations


• Blackout date management for holidays and closures


• Integration with Tookan and CIGO for real-time GPS driver tracking


• Delivery task assignment with ETA, driver info, signature capture, and customer rating

Order Fulfillment & Operations

The operations dashboard handles the full post-order workflow:

• Order assignment to shoppers by delivery date


• Line-item-level tracking: quantity found, missing, substituted, damaged, not delivered


• Employee shift management with wage calculation, gas cost, and receipt tracking


• Delivery reports from shoppers with automatic order status updates


• Batch pricing — schedule future price and inventory changes across products, auto-applied via daily cron jobs


• B2B company management with spending analytics, order frequency, and customer linking

Accounting Integration

Automated Xero accounting integration:

• Auto-posting of orders, payments, adjustments, and refunds to Xero general ledger


• Account mapping for sales, missing items, tips, shipping, discounts, and each payment gateway


• Per-tenant Xero credentials and account configuration

Technology Stack