alaiy-tech/alaiy_os_connector_shopify

Purpose and runtime

A Frappe/ERPNext extension that isolates Shopify-specific integration from Alaiy OS. It synchronizes Shopify Admin GraphQL data with Frappe DocTypes for products, orders, inventory, customers, taxonomy, collections, tags, and publication channels. It requires alaiy_os and erpnext; execution is through Frappe HTTP/RPC, document hooks, scheduler jobs, and webhook endpoints.

App registration and operational entry points

The connector registers itself with Alaiy OS during migration and exposes dotted-path integration methods rather than modifying core OS code. Setup enables credentials, defaults, mappings, custom fields, and webhooks.

• alaiy_os_connector_shopify/hooks.py

• alaiy_os_connector_shopify/setup/install.py

• alaiy_os_connector_shopify/connector_meta.py

• alaiy_os_connector_shopify/doctype/shopify_connector_settings/shopify_connector_settings.py

Operator-facing entry points are the Shopify desk page and API methods for sync, connectivity verification, order clearing/retry, and webhook receipt.

• alaiy_os_connector_shopify/page/shopify/shopify.js

• alaiy_os_connector_shopify/api/sync.py

• alaiy_os_connector_shopify/api/webhooks.py

Shopify transport and sync safety

The Shopify boundary is centralized around authentication and an Admin GraphQL client, including pagination and API throttling. Sync guardrails prevent feedback loops and duplicate external writes: content fingerprints skip unchanged payloads, per-record locking serializes work, and retry entries persist recoverable failures.

• alaiy_os_connector_shopify/shopify/auth.py

• alaiy_os_connector_shopify/shopify/graphql_client.py

• alaiy_os_connector_shopify/shopify/sync_engine/fingerprint.py

• alaiy_os_connector_shopify/shopify/sync_engine/retry_queue.py

• alaiy_os_connector_shopify/shopify/sync_guard.py

Product and catalog pipeline

Product import/export is decomposed around a canonical Shopify-to-Item/listing representation, then domain-specific transformations for variants, media, pricing, SEO, taxonomy, tags, collections, lifecycle status, and stock. Product DocTypes retain Shopify-facing listing, variant, image, and metafield state; hooks propagate relevant Frappe Item changes outward while inbound changes are marked to avoid echoing.

• alaiy_os_connector_shopify/shopify/product/importer.py

• alaiy_os_connector_shopify/shopify/product/export.py

• alaiy_os_connector_shopify/shopify/product/listing.py

• alaiy_os_connector_shopify/shopify/product/variants.py

• alaiy_os_connector_shopify/doctype/shopify_product_listing/shopify_product_listing.json

Order ingestion and fulfillment flow

Orders arrive through pulls and webhooks, are normalized/upserted into ERPNext Sales Orders, and resolve customer, address, warehouse, items, taxes, discounts, shipping, and currency. Subsequent Shopify updates drive amendments/cancellations/notes and fulfillment-related Delivery Notes; invoice/payment handling is a separate stage. Outbound order modules support reverse updates where configured.

• alaiy_os_connector_shopify/shopify/order/pull.py

• alaiy_os_connector_shopify/shopify/order/upsert.py

• alaiy_os_connector_shopify/shopify/order/webhook.py

• alaiy_os_connector_shopify/shopify/order/invoice.py

• alaiy_os_connector_shopify/shopify/order/push.py

Inventory and location boundary

Inventory is outbound from Alaiy OS to Shopify. A mapping layer connects ERPNext warehouses to Shopify locations, allowing either a default location or multi-location stock publication.

• alaiy_os_connector_shopify/shopify/inventory_sync.py

• alaiy_os_connector_shopify/shopify/pull_stock_from_shopify.py

• alaiy_os_connector_shopify/doctype/shopify_location_map/shopify_location_map.json

• alaiy_os_connector_shopify/doctype/shopify_location/shopify_location.py

Persistent integration state and evolution

Frappe DocTypes provide settings, remote entity caches, listing metadata, operational logs, retry records, and sync identity state. Patches evolve deployed customer data, especially listing normalization and legacy-field removal, so migration is an architectural lifecycle boundary.

• alaiy_os_connector_shopify/doctype/shopify_sync_log/shopify_sync_log.json

• alaiy_os_connector_shopify/doctype/shopify_synced_entity/shopify_synced_entity.json

• alaiy_os_connector_shopify/doctype/shopify_retry_queue_entry/shopify_retry_queue_entry.json

• alaiy_os_connector_shopify/patches.txt