Dashboard Products Providers Logs Documentation

Documentation

Shopify Supplier Inventory Sync

Status

Version: 1.0 (Core completed)

INSTALLATION

1. Create Shopify Location

Create a new Shopify location for the supplier. ( Settings -> Locations -> Add Location )

Example:

Comstedt

or

Atlok

After creating the location, open it in the Shopify Admin.

The Location ID is the numeric value at the end of the URL.

Example:

https://admin.shopify.com/store/your-store/settings/locations/12345678901

In this example:

Location ID = 12345678901

Use this value in the provider configuration.

2. Import Shopify Flow

Import the supplied Shopify Flow.

Update the following values:

  • Provider order tag (for example SendToComstedt)
  • Provider product tag (for example Comstedt-Drop)
  • Recipient e-mail address

3. Tag Products

Add a provider tag to all products handled by the supplier.

Examples:

Comstedt-Drop
Atlok-Drop

The tag name is configurable and may be changed if required.

4. Add Provider

Open:

Dashboard → Providers

Create a new provider and configure:

  • Name
  • Driver
  • Supplier location
  • Update interval
  • Connection settings

Enable the provider.

5. Test Connection

Use Test Connection to verify that the supplier feed is accessible.

The provider status should change to:

Connected

6. Run Initial Maintenance

Run the following actions once:

  1. Fetch Provider
  2. Sync Inventory
  3. Update Supplier Tags

or simply run:

Full Maintenance

7. Enable Shopify Flow

After verifying that:

  • Provider connection works
  • Inventory synchronization is working correctly
  • Supplier tags are updated correctly

Open the imported Shopify Flow and click:

Turn on workflow

The maintenance system is now fully operational.

OVERVIEW

Shopify Maintenance System synchronizes supplier inventory to Shopify using a modular provider architecture.

The system consists of:

  • Dashboard
  • Maintenance Runner
  • Job Manager
  • Provider Drivers
  • Live Log Viewer
  • Automatic Maintenance (Cron)

Requirements

  • PHP 8.1.34 +
  • Shopify Admin API
  • cURL
  • phpseclib v3 (SFTP)
  • Cron access

Current Features

Dashboard

Implemented:

  • Fetch Provider
  • Sync Inventory
  • Update Supplier Tags
  • Full Maintenance

Features:

  • Provider selector
  • Action selector
  • Live log output
  • Runtime polling
  • Step indicator
  • Success / Failed status
  • Execution duration

Dashboard never executes maintenance directly.

All maintenance operations are started through:

maintenance_runner.php

Job System

JobManager stores execution state inside:

data/jobs/

Each job contains:

  • running
  • success
  • duration
  • step
  • log

Dashboard polls:

status.php

every 500 ms.

Cron execution bypasses JobManager.

Only dashboard executions create jobs.

Maintenance Runner

maintenance_runner.php

Single entry point for all maintenance operations.

Used by:

  • Dashboard
  • Cron

Supported actions:

fetch
sync
tags
full

Providers

Current providers:

  • HTTP (Atlok)
  • SFTP (Comstedt)
  • WooCommerce (Implemented, not production tested)

Architecture supports unlimited providers.

Each provider contains:

enabled
driver
settings
location_id
order_tag
product_tag

Fetch

Implemented.

Supports:

  • interval checking
  • provider cache
  • force mode
  • provider selection

Dashboard:

Runs disabled providers when explicitly selected.

Cron:

Runs only enabled providers.

Fetched inventory is stored as:

data/cache/{provider}.json

Cron automatically respects provider fetch intervals.

Sync

Implemented.

Supports:

  • provider selection
  • force mode
  • Shopify inventory updates

Dashboard:

Runs disabled providers when explicitly selected.

Cron:

Runs only enabled providers.

Synchronization always reads supplier inventory from cache.

Providers are never contacted directly during synchronization.

Update Supplier Tags

Implemented.

Updates:

  • SendToProvider tag
  • SoldOut tag

Uses GraphQL.

Only enabled providers are processed.

(No force mode.)

Full Maintenance

Runs:

  1. Fetch
  2. Sync
  3. Update Supplier Tags

Progress is written into log as:

@STEP:fetch
@STEP:sync
@STEP:tags
@STEP:finished

Dashboard filters these markers and displays graphical progress.

Logging

Daily log files:

logs/YYYY-MM-DD.log

Logger supports:

setLogHook()

Dashboard receives live log output through JobManager.

Log Viewer supports:

  • Daily logs
  • Cache inspection

Cleanup

Automatic cleanup implemented.

Logs:

cleanupLogs()

Jobs:

cleanupJobs()

Configuration:

'cleanup' => [

    'jobs_days' => 7,

    'logs_days' => 30,

]

Cron

Cron executes:

maintenance_runner.php

Example:

php maintenance_runner.php cron full all 0

Cron:

  • does not create JobManager jobs
  • does not use dashboard polling
  • writes normal log files
  • respects provider fetch intervals

Directory Structure

app/
    ajax/
    js/

inc/
    helper.php
    JobManager.php
    ProcessManager.php

providers/
    http.php
    sftp.php
    woocommerce.php

data/
    cache/
    jobs/

logs/

maintenance_runner.php

fetch_provider.php
sync_stock.php
update_supplier_tags.php
full_maintenance.php




Files

File Purpose
maintenance_runner.php Main entry point for all maintenance operations.
fetch_provider.php Downloads supplier inventory.
sync_stock.php Synchronizes cached supplier inventory to Shopify.
update_supplier_tags.php Updates Shopify product tags.
full_maintenance.php Runs complete maintenance sequence.


Directories

Directory Purpose
app/ Dashboard, UI and AJAX endpoints.
providers/ Provider drivers.
inc/ Core classes.
data/ Cached supplier inventory.
data/jobs/ Dashboard job status.
logs/ Daily application logs.




Remaining Tasks

High Priority

WooCommerce Provider

  • Production testing
  • Validation with real WooCommerce stores

Medium Priority

  • Dashboard provider status
  • Dashboard last execution time

Future Ideas

  • Statistics

Architecture Notes

Dashboard and Cron use exactly the same maintenance runner.

Provider drivers remain completely independent from maintenance logic.

Maintenance functions remain independent from Dashboard.

Dashboard only starts jobs and monitors their progress.

Synchronization always reads supplier inventory from cache.

JavaScript contains no business logic.

Design Principles

  • Dashboard contains no business logic.
  • Maintenance Runner is the single execution entry point.
  • Provider drivers are independent modules.
  • Synchronization always uses cached supplier data.
  • Cron and Dashboard share the same maintenance framework.
  • JavaScript is responsible only for the user interface.
  • Providers can be added without changing maintenance logic.

Current State

Core maintenance framework is completed.

Version 1.0 is feature complete.

Remaining work consists mainly of:

  • Production testing
  • UI polishing
  • WooCommerce provider validation