Orbit Commerce Headless Omnichannel E-Commerce & Atomic Inventory Depletion

1. Executive Capability Brief & Operational Impact Benchmark

Retailers operating separate software stacks for online e-commerce websites and physical in-store point-of-sale terminals suffer from systemic inventory divergence:

1. Overselling & Phantom Stock-Outs: When online orders do not immediately decrement shelf inventory, physical walk-in customers purchase the final units in store while digital shoppers place conflicting orders, resulting in embarrassing order cancellations.
2. Delayed In-Store Packing: Online orders sitting in email inboxes or third-party web portals require manual re-keying into cash registers, causing 20-to-40 minute packing delays that destroy same-day delivery SLAs.
3. Disjointed Customer Identity: Customers purchasing both in-store and online have fragmented purchase histories, preventing consolidated loyalty point redemption and customer khata credit settlements.
4. Complex Click-and-Collect Handover: Store staff searching through printed paper slips struggle to verify customer pickup identities, resulting in wrong-order handovers and uncollected balance losses.

Orbit Commerce eliminates this divide by powering digital storefronts directly from the unified retail engine. Online checkouts immediately decrement the physical retail store stock ledger using reason COMMERCE_ONLINE_SALE, ring hardware arrival chimes on cashier terminals within 500 milliseconds, and queue orders for rapid bag packing and click-and-collect handoff.

2. Multi-Tenant Storefront Resolution & Edge Routing Topology

The headless storefront edge ingress routes consumer web traffic to isolated tenant databases while sharing a unified application server cluster.

Hostname Resolution Pipeline

When an HTTP request strikes the storefront edge ingress:

1. Host Extraction: Ingress captures the Host header (e.g., shop.organicsupermarket.com).
2. Domain Matching: Queries the tenant domain registry. If a custom domain matches, the corresponding tenant record is resolved immediately from memory cache.
3. Fallback Slug Resolution: If accessing via multi-tenant subdomain (e.g., organics.frontorbit.com/store), the path prefix resolves the tenant.
4. Tenant Context Binding: Sets the tenant security context for the database transaction. Database Row-Level Security automatically restricts queries to that tenant alone.
5. Location Catalog Binding: Maps the online storefront to the designated fulfillment location (e.g., Flagship Central Supermarket WH-01), guaranteeing catalog queries reflect actual physical stock on hand.

Codebase Anchors & Grounded Architecture

The omnichannel storefront sync and click-and-collect fulfillment engine is implemented across the consumer storefront and backend application server:

• Storefront Client Application: Dynamic consumer e-commerce storefront (apps/storefront/), providing multi-tenant catalog resolution, localized inventory visibility, and web checkout.
• Backend Fulfillment Service: Order fulfillment and arrival dispatch pipeline (order-fulfillment.service.ts at apps/api/src/modules/commerce/services/order-fulfillment.service.ts), providing pollAlerts, verifyPickup, completePickup, and restockCancelledOrder.
• Relational Persistence Schema: The orders, order_fulfillments, and order_items tables in the relational persistence kernel, synchronizing reservation timestamps, click-and-collect codes, and pickup completion states.

3. Omnichannel Dispatch Console User Interface

The Omnichannel Dispatch Console runs on in-store cashier touchscreens and dedicated fulfillment tablets in the packing zone. Cashier workstations invoke pollAlerts against the fulfillment backend at sub-second frequency. Incoming web orders alert operators with sound chimes and color-coded status badges.

4. Atomic Inventory Depletion Mechanics & Kit Bill of Materials

When a customer completes an online order, Orbit Commerce guarantees inventory consistency through atomic database transactions.

Standard Item Inventory Depletion

For standard discrete products, the transaction decrements shelf inventory and logs an immutable stock movement:

Database Transaction Boundary:
1. Item row locked via SELECT FOR UPDATE:
   itemId: "SKU-OIL-1001", locationId: "loc-wh-01"
2. Decrement Item.stockQuantity by order line quantity:
   UPDATE items SET "stockQuantity" = "stockQuantity" - 2 WHERE id = "SKU-OIL-1001";
3. Insert StockMovement record:
   - tenantId: "tnt_84920"
   - itemId: "SKU-OIL-1001"
   - locationId: "loc-wh-01"
   - quantity: -2
   - reason: "COMMERCE_ONLINE_SALE"
   - referenceId: "inv-2026-9041"
4. Audit Log Emission:
   - action: "COMMERCE_STOREFRONT_CHECKOUT"
   - entity: "Invoice"

If the customer purchases two bottles while only one bottle remains, the SQL balance constraint rejects the update, rolling back the transaction. The customer receives an immediate out-of-stock notification before their payment method is charged.

Kit Bill of Materials (BOM) Decomposition

Retail kits (e.g., "Gourmet Breakfast Gift Basket" containing 1 jar of honey, 1 bag of tea, and 1 package of biscuits) do not have independent physical stock. Instead, purchasing the kit atomically depletes each constituent component:

Kit Purchase: 1x "Gourmet Breakfast Basket" (SKU-KIT-01)
BOM Resolution:
├── Component 1: 1x Raw Honey 1kg (SKU-HNY-4011)     -> Decrement -1
├── Component 2: 1x Green Tea Leaf 250g (SKU-TEA-0091)-> Decrement -1
└── Component 3: 1x Butter Biscuits 200g (SKU-BSC-102)-> Decrement -1

Atomic Execution:
Each component item is updated within the same transaction.
Three distinct StockMovement records are inserted, each citing:
reason: "COMMERCE_ONLINE_SALE", referenceId: "inv-2026-9041"

This prevents component stock desynchronization: if the warehouse runs out of tea, the gift basket is immediately marked out of stock on the storefront, even if honey and biscuits remain plentiful.

5. Fulfillment State Machine & Click-and-Collect Handover Protocol

Online orders advance through five deterministic fulfillment states. Transitions are strictly validated to prevent illegal state jumps:

   [UNFULFILLED] ─── (Packer Claims) ───> [PREPARING]
         │                                     │
         │                                     ├─── (Staged on Shelf) ───> [READY_FOR_PICKUP]
         │                                     │                                 │
         │                                     └─── (Handed to Courier)─┐        │ (Customer Collects)
         │                                                              │        │
         ▼                                                              ▼        ▼
   [CANCELLED] <──────────────────────── (Restock Execution) ─────── [DISPATCHED / DELIVERED]

Allowed State Transitions

Click-and-Collect Pickup Handover SOP

When a customer arrives at the retail store to claim an order:

1. Pickup Code Presentation: Customer presents 4-digit pickup code (e.g., PICK-8912) or QR barcode on their smartphone screen.
2. Cashier Code Lookup: Cashier presses F9 on POS keyboard; enters code or scans QR barcode.
3. Verification Screen: Inspector retrieves order via verifyPickup:
   • Confirms order is in READY_FOR_PICKUP status.
   • Inspects payment status: if paid online, remaining balance displays $0.00. If pay-at-store, displays outstanding balance.
4. Tender Settlement (If Unpaid): If balance is outstanding, cashier collects tender via cash or card.
5. Physical Handover: Cashier retrieves package from staging shelf; clicks Complete Pickup Handover (invoking completePickup). System transitions status to DELIVERED and prints vector A4 receipt or 80mm thermal handover docket.

6. Vector A4 Commercial Invoice & QR Cryptographic Verification

Every completed omnichannel order generates an authoritative vector A4 invoice rendered via the native server PDF engine.

Invoice Layout Architecture

The generated PDF includes full commercial and fiscal compliance metadata:

1. Header & Corporate Identity: Vector store SVG logo, commercial registration number, tax registration number (TRN), and branch physical address.
2. Customer Metadata: Name, phone number, shipping/pickup address, and unique customer reference.
3. Line Item Matrix: Product description, SKU, unit rate, quantity, tax rate percentage, tax amount, and line gross total.
4. Financial Totals: Subtotal, promotional discounts, output tax total, and final payable amount.
5. Cryptographic Verification QR: Embedded high-resolution vector QR code containing standard TLV or signed verification URL, allowing fraud auditors and delivery drivers to verify document authenticity.

Document Header: FRONTORBIT COMMERCE OS TAX INVOICE
Branch Location: Central Logistics Flagship
Invoice Number : #INV-2026-9041
Tax Reg Number : TRN 310124892000003
Invoice Date   : 2026-10-08

Customer Name  : Fatima Al-Zahrani (+966 50 123 4567)
Fulfillment    : Click-and-Collect (Code: PICK-8912)

SKU            Description                  Qty    Rate     VAT     Line Total
SKU-OIL-1001   Olive Oil Organic 1L           2   18.50   15.0%        $ 42.55
SKU-RICE-500   Aged Basmati Rice 5kg          1   12.00   15.0%        $ 13.80

Subtotal       : $49.00
Promotions     : -$4.00
Output VAT 15% : $6.75
Total Payable  : $51.75
Payment Status : PAID ONLINE (CARD) · Tender Ref: STR-TXN-88192
Cryptographic  : Signed Document Authority QR Embedded

7. Deviation Handling & Exception Protocols

Omnichannel fulfillment requires precise recovery protocols when online and offline operations conflict:

8. High-Frequency Triage & Architectural FAQs

How does Orbit Commerce handle simultaneous checkout attempts for the last remaining item?

The database engine serializes checkout requests using row-level write locks. When two concurrent shoppers attempt to purchase the final unit of SKU-OIL-1001, the first transaction to acquire the row lock decrements stock from 1 to 0 and commits successfully. The second transaction observes stockQuantity reaches 0, fails the balance validation check, and rolls back cleanly without charging the customer.

What happens if an online order is placed while the physical retail store network is offline?

Online orders are accepted and queued by the central cloud application server. The central cloud database atomically decrements the cloud inventory balance. When the local store POS terminal regains network connectivity, it polls /api/bff/commerce/fulfillment/alerts, receives the queued orders, sounds the arrival chime, and displays the orders for immediate packing.

Can customers pay cash upon in-store pickup for an order placed online?

Yes. Orbit Commerce supports both pre-paid online checkouts and pay-at-store click-and-collect reservations. When an order is placed with PAY_AT_STORE, the order is created with paidAmount of 0. At customer pickup, the cashier enters the pickup code into the POS terminal, collects tender via cash, card, or split payment, and completes the handover within the standard register shift.

9. Related Operations & Lateral Internal Links

Maintain end-to-end operational mastery across inventory, cashiering, and store logistics:

• Master split-tender checkout resilience: Split-Tender Multi-Rail Cashiering & Offline Outbox Resilience.
• Multi-location warehouse transfers: Inter-Store Stock Transfers & In-Transit Custody Tracking.
• Cryptographic invoice clearance: ZATCA Phase 2 E-Invoicing & Cryptographic Outbox Clearance.
• Barcode scanner wedge configurations: EAN-13 Scale Barcodes & Scanner Wedge Processing.
• Restaurant and table ordering systems: Orbit Dine POS Terminal Operations.