# alaiy-tech/alaiy_os_connector_shopify architecture

> Architecture diagram of the GitHub repository alaiy-tech/alaiy_os_connector_shopify, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alaiy-tech/alaiy_os_connector_shopify
- Repository: https://github.com/alaiy-tech/alaiy_os_connector_shopify

## Overview

#### 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`

Main entry points: [`alaiy_os_connector_shopify/shopify/product/importer.py`](https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/shopify/product/importer.py) (Product import/export), [`alaiy_os_connector_shopify/shopify/order/pull.py`](https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/shopify/order/pull.py) (Order pull & webhook), [`alaiy_os_connector_shopify/api/sync.py`](https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/api/sync.py) (Sync RPC), [`alaiy_os_connector_shopify/shopify/graphql_client.py`](https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/shopify/graphql_client.py) (Shopify Admin GraphQL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Frappe Runtime"]
  node_app_hooks["App registration<br/>Frappe hooks<br/>[hooks.py]"]
  node_setup["Setup &amp; migration<br/>installer<br/>[install.py]"]
  node_settings["Connector settings<br/>DocType controller"]
  node_operator_ui["Shopify desk page<br/>Frappe page"]
  node_sync_api["Sync RPC<br/>Frappe API<br/>[sync.py]"]
  node_webhook_api["Webhook endpoint<br/>Frappe API<br/>[webhooks.py]"]
end

subgraph group_transport["Shopify Boundary"]
  node_graphql{{"Shopify Admin GraphQL<br/>API client<br/>[graphql_client.py]"}}
  node_auth["Shopify authentication<br/>auth provider<br/>[auth.py]"]
  node_sync_guard["Sync guardrails<br/>sync safety<br/>[sync_guard.py]"]
  node_retry_queue["Retry processing<br/>durable retry<br/>[retry_queue.py]"]
end

subgraph group_catalog["Catalog &amp; Inventory"]
  node_product_pipeline["Product import/export<br/>catalog pipeline<br/>[importer.py]"]
  node_product_listing[("Product listing state<br/>DocType")]
  node_inventory_sync["Inventory publication<br/>stock sync<br/>[inventory_sync.py]"]
  node_location_mapping[("Warehouse-location mapping<br/>DocType")]
end

subgraph group_orders["Order Processing"]
  node_order_ingestion["Order pull &amp; webhook<br/>order intake<br/>[pull.py]"]
  node_sales_order_upsert["Sales Order upsert<br/>ERPNext adapter<br/>[upsert.py]"]
  node_fulfillment_billing["Fulfillment &amp; billing<br/>order lifecycle<br/>[invoice.py]"]
end

subgraph group_state["Integration State"]
  node_integration_state[("Sync identity &amp; logs<br/>DocTypes")]
  node_patches["Data evolution patches<br/>migration manifest<br/>[patches.txt]"]
end

node_app_hooks -->|"runs on install/migrate"| node_setup
node_setup -->|"provisions"| node_settings
node_operator_ui -->|"invokes"| node_sync_api
node_webhook_api -->|"routes order events"| node_order_ingestion
node_sync_api -->|"starts catalog sync"| node_product_pipeline
node_sync_api -->|"starts order sync"| node_order_ingestion
node_settings -->|"supplies credentials"| node_auth
node_auth -->|"authorizes"| node_graphql
node_product_pipeline -->|"imports and exports"| node_graphql
node_product_pipeline -->|"persists listing state"| node_product_listing
node_inventory_sync -->|"resolves locations"| node_location_mapping
node_inventory_sync -->|"publishes stock"| node_graphql
node_order_ingestion -->|"pulls order data"| node_graphql
node_order_ingestion -->|"normalizes and upserts"| node_sales_order_upsert
node_sales_order_upsert -->|"drives lifecycle records"| node_fulfillment_billing
node_sync_guard -->|"guards writes"| node_product_pipeline
node_sync_guard -->|"guards publication"| node_inventory_sync
node_sync_guard -->|"prevents duplicate processing"| node_order_ingestion
node_retry_queue -->|"persists failures"| node_integration_state
node_retry_queue -.->|"retries through sync actions"| node_sync_api
node_product_pipeline -->|"tracks external identities"| node_integration_state
node_sales_order_upsert -->|"tracks order sync state"| node_integration_state
node_patches -->|"migrates persisted data"| node_integration_state

click node_app_hooks "https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/hooks.py"
click node_setup "https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/setup/install.py"
click node_sync_api "https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/api/sync.py"
click node_webhook_api "https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/api/webhooks.py"
click node_graphql "https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/shopify/graphql_client.py"
click node_auth "https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/shopify/auth.py"
click node_sync_guard "https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/shopify/sync_guard.py"
click node_retry_queue "https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/shopify/sync_engine/retry_queue.py"
click node_product_pipeline "https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/shopify/product/importer.py"
click node_inventory_sync "https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/shopify/inventory_sync.py"
click node_order_ingestion "https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/shopify/order/pull.py"
click node_sales_order_upsert "https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/shopify/order/upsert.py"
click node_fulfillment_billing "https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/shopify/order/invoice.py"
click node_patches "https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/patches.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_hooks,node_setup,node_settings,node_operator_ui,node_sync_api,node_webhook_api toneBlue
class node_graphql,node_auth,node_sync_guard,node_retry_queue toneAmber
class node_product_pipeline,node_product_listing,node_inventory_sync,node_location_mapping toneMint
class node_order_ingestion,node_sales_order_upsert,node_fulfillment_billing toneRose
class node_integration_state,node_patches toneIndigo
```

## Components

### Frappe Runtime

- [App registration](https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/hooks.py): Frappe hooks · Registers migration and Alaiy OS integration methods. · `alaiy_os_connector_shopify/hooks.py`
- [Setup & migration](https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/setup/install.py): installer · Provisions credentials, mappings, fields, and webhooks. · `alaiy_os_connector_shopify/setup/install.py`
- **Connector settings**: DocType controller · Stores and manages Shopify connection configuration.
- **Shopify desk page**: Frappe page
- [Sync RPC](https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/api/sync.py): Frappe API · Operator actions invoke synchronization and recovery operations. · `alaiy_os_connector_shopify/api/sync.py`
- [Webhook endpoint](https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/api/webhooks.py): Frappe API · `alaiy_os_connector_shopify/api/webhooks.py`

### Shopify Boundary

- [Shopify Admin GraphQL](https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/shopify/graphql_client.py): API client · Authenticated, paginated, throttled Shopify transport. · `alaiy_os_connector_shopify/shopify/graphql_client.py`
- [Shopify authentication](https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/shopify/auth.py): auth provider · `alaiy_os_connector_shopify/shopify/auth.py`
- [Sync guardrails](https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/shopify/sync_guard.py): sync safety · Locks records and fingerprints payloads to prevent duplicate or echo writes. · `alaiy_os_connector_shopify/shopify/sync_guard.py`
- [Retry processing](https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/shopify/sync_engine/retry_queue.py): durable retry · Persists and replays recoverable sync failures. · `alaiy_os_connector_shopify/shopify/sync_engine/retry_queue.py`

### Catalog & Inventory

- [Product import/export](https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/shopify/product/importer.py): catalog pipeline · Canonical listing flow transforms Shopify products and Frappe Items. · `alaiy_os_connector_shopify/shopify/product/importer.py`
- **Product listing state**: DocType · Retains Shopify listing, variant, image, and metafield state.
- [Inventory publication](https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/shopify/inventory_sync.py): stock sync · Publishes Alaiy OS stock to Shopify locations. · `alaiy_os_connector_shopify/shopify/inventory_sync.py`
- **Warehouse-location mapping**: DocType · Supports default and multi-location stock publication.

### Order Processing

- [Order pull & webhook](https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/shopify/order/pull.py): order intake · Normalizes Shopify orders from polling and event delivery. · `alaiy_os_connector_shopify/shopify/order/pull.py`
- [Sales Order upsert](https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/shopify/order/upsert.py): ERPNext adapter · Resolves customers, items, taxes, shipping, currency, and addresses. · `alaiy_os_connector_shopify/shopify/order/upsert.py`
- [Fulfillment & billing](https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/shopify/order/invoice.py): order lifecycle · Applies Shopify lifecycle changes and handles invoices and payments. · `alaiy_os_connector_shopify/shopify/order/invoice.py`

### Integration State

- **Sync identity & logs**: DocTypes · Stores remote identities, operational logs, and retry records.
- [Data evolution patches](https://github.com/alaiy-tech/alaiy_os_connector_shopify/blob/main/alaiy_os_connector_shopify/patches.txt): migration manifest · Evolves deployed integration data and legacy fields. · `alaiy_os_connector_shopify/patches.txt`

## Connections

- App registration → Setup & migration: runs on install/migrate
- Setup & migration → Connector settings: provisions
- Shopify desk page → Sync RPC: invokes
- Webhook endpoint → Order pull & webhook: routes order events
- Sync RPC → Product import/export: starts catalog sync
- Sync RPC → Order pull & webhook: starts order sync
- Connector settings → Shopify authentication: supplies credentials
- Shopify authentication → Shopify Admin GraphQL: authorizes
- Product import/export → Shopify Admin GraphQL: imports and exports
- Product import/export → Product listing state: persists listing state
- Inventory publication → Warehouse-location mapping: resolves locations
- Inventory publication → Shopify Admin GraphQL: publishes stock
- Order pull & webhook → Shopify Admin GraphQL: pulls order data
- Order pull & webhook → Sales Order upsert: normalizes and upserts
- Sales Order upsert → Fulfillment & billing: drives lifecycle records
- Sync guardrails → Product import/export: guards writes
- Sync guardrails → Inventory publication: guards publication
- Sync guardrails → Order pull & webhook: prevents duplicate processing
- Retry processing → Sync identity & logs: persists failures
- Retry processing → Sync RPC: retries through sync actions
- Product import/export → Sync identity & logs: tracks external identities
- Sales Order upsert → Sync identity & logs: tracks order sync state
- Data evolution patches → Sync identity & logs: migrates persisted data