Data sync

How your catalog, stock, orders and customers reach Conviro: the continuous (event) sync, the initial historical sync, re-syncs, repair, and where to watch progress. Plan §20 items 6, 7 and 14; P4.1–P4.3. Code: AiChat/Service/Sync/*, AiChat/Service/Inventory/*, backend magento-commerce-sync.service.ts. Read 2026-09-24; measured on the local 2.4.7-p4 stack only (sync-jobs.sh 57/57, catalog-resync.sh 21/21).

Continuous sync (events)

Changes in Magento are queued locally and delivered by cron every minute (Architecture); the event reference lists every trigger and field.

Data	Sent when	Switch
Products	saved or deleted in the admin / by API; disabled products are sent as disabled	Sync Products to KB (default off; on after wizard step 5 Catalog)
Stock	changed in the admin, by the MSI API, or by Magento's catalog import; one event per product, the latest state wins	Sync Products to KB
Orders	placed, state/status changed, shipped (new shipment), refunded	Send Order Events (default on)
New customers	storefront registration → a lead in Conviro	Create Leads on Registration (default on)
Carts, failed payments	see Cart recovery and payment assist	off by default, need confirmation

Not covered by events (Magento does not dispatch the product-save event for them): the catalog import of product data and the admin Update attributes mass action. Run Re-sync catalog after such changes.

Initial historical sync

Started from wizard step 5 (Save and start initial sync); each type is a background job run by Magento cron.

Job	What it sends	Scope	Event type
Catalog	every enabled, website-assigned product with visibility catalog, search or both, built for the default store view; configurable children travel inside their parent	catalog-wide	`product.updated` with `resync: true`
Inventory	the current stock of every eligible product	catalog-wide	`inventory.updated` with `resync: true`
Order history	orders of the selected store views created inside the window (30 / 90 / 365 days, default 90), window fixed when the job starts	selected store views	`order.synced`
Customers (opt-in)	existing accounts of the selected store views (admin-created accounts count as the default store view)	selected store views	`customer.synced`

History is quiet by construction: Conviro stores it in commerce_orders / commerce_customers and nothing else happens — no leads, e-mails, notifications, flows or cart-recovery cancellations. Orders keep order number, status, total, currency, item count, guest flag, dates and a one-way hash of the e-mail; customers keep id, group, website, account date and the hash. No names, addresses, phone numbers or line items.

How jobs run

One job of each type at a time: a second start while one runs does nothing.
200 items per job type per minute. Each item's queue insert and the job's progress update commit together, so a crash resumes exactly where it stopped (measured: a process killed inside an item's transaction resumed with nothing lost or doubled).
Back-pressure: no new batch while 1,000 events wait for delivery.
A job stops (status failed, with the reason) when the module is disabled, the API key is removed (Disconnect does this and cancels every running job), or its switch is turned off: Sync Products to KB for catalog and inventory, Send Order Events for orders, the wizard's Customers box for customers.
A job never runs inside a web request; an idle cron run costs one indexed query per type.

Re-sync and repair (Integration Health card)

Button	Does	Notes
Re-sync catalog	the catalog job again	Refused while Sync Products to KB is off. A re-synced product whose knowledge-base text did not change costs Conviro no re-embedding and no cache scan.
Re-sync inventory	the inventory job again	Coalesces with stock events already waiting.
Re-sync recent orders (N days)	the order-history job	N = the wizard's window; 30 when you chose none.
Import customers	the customer job	Shown only when Customers was ticked in step 5.
Repair failed items	fixes events that failed for good (`dead`) or were dropped, up to the newest one at start	Payload still stored → re-queued with a fresh retry budget. Payload gone → rebuilt from Magento's current data: product → `product.updated` (or `product.deleted` if the SKU no longer exists), order → `order.synced`, stock → `inventory.updated`; the original is marked `repaired`. Cart, payment, customer, test and progress events are skipped (not rebuilt). Measured: 1 requeued, 4 rebuilt, 2 skipped; a second repair rebuilt nothing.
Retry failed	puts `dead` and `blocked` events back in the queue as they are	For after you fixed the cause (e.g. a rejected API key).

Each button is disabled while its job runs.

Watching progress

Magento: the Integration Health card shows every job type — progress bar (100 % only when completed), processed / failed / skipped counts, requested / started / finished times, the last error, and a note when a job has not moved for over 15 minutes (Magento cron is not running it; the same threshold the Conviro dashboard uses) or is paused by back-pressure. Never-run types say Not run yet.
Conviro dashboard: the Magento card's store status ends with Sync jobs: the latest job of each type with the same numbers, a warning when a queued or running job has not reported for over 15 minutes, and how many orders and customers Conviro holds, live vs from history. Jobs report through the signed sync.job.progress event, once per batch and on every state change.

The nightly REST pull (Conviro side)

Independently of the module, a workspace with Conviro's KB sync enabled has Conviro pull the product list over REST every night (02:00 server time). It renders the same knowledge-base text as product events, keeps products that are visible in catalog or search, and deactivates entries for products no longer listed — only after a complete listing. A product that an event has described keeps the attribute and variant blocks the module sent.

Known limits

Knowledge-base entries are per SKU, not per store view: re-sync text is the default store view's.
Product types measured: simple and configurable. Bundle, grouped, virtual and downloadable products, customer-group / tier prices and catalog price rules have no fixture yet.
Stock on a website assigned to a non-default MSI stock has not been measured.