# mrpondi/woocommerce_conduit architecture

> Architecture diagram of the GitHub repository mrpondi/woocommerce_conduit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mrpondi/woocommerce_conduit
- Repository: https://github.com/mrpondi/woocommerce_conduit

## Overview

##### Project type and purpose
– This is a Frappe “app” (a plug-in module for the Frappe/ERPNext framework) named “woocommerce_conduit.”
– Its job is to integrate (synchronize) data between a WooCommerce e-commerce site (external REST API) and a Frappe server (documents/Doctypes, database, web UI, scheduler).

##### File structure
Top-level:
- configuration files (.editorconfig, .eslintrc, pyproject.toml, modules.txt, patches.txt, hooks.py)
- endpoint.py & woocommerce_api.py (custom API wrappers / whitelisted methods)
- tasks/ (background jobs for syncing orders, items, prices)
- templates/pages/ (HTML/Jinja templates for custom UI pages)
- fixtures/ (JSON fixtures for initial DocType setup)
Sub-package “woocommerce_conduit/woocommerce_conduit” contains:
- doctype/ – JSON metadata, Python controllers, JS scripts, tests for each DocType (woocommerce_server, woocommerce_product, woocommerce_order, logs, settings, shipping rules, etc.)

##### README for insights
– Installs as a Frappe app via bench CLI.
– Uses Frappe scheduler and background jobs for periodic sync.
– Has pre-commit, GitHub Actions for CI/linting.
– Future plans: webhooks, improved field mapping.

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% External Systems
  WCAPI["WooCommerce REST API"]:::external
  CI["GitHub Actions / Bench CLI"]:::external

  %% Frappe Core Services
  subgraph "Frappe Application Server"
    direction TB
    WebUI["Web UI / Desk"]:::core
    Scheduler["Scheduler"]:::core
    ORM["MariaDB (Frappe ORM)"]:::core
  end

  %% woocommerce_conduit Module
  subgraph "woocommerce_conduit Module"
    direction TB
    subgraph "Config & Entry"
      Hooks["hooks.py"]:::module
      ModulesTxt["modules.txt"]:::module
      PatchesTxt["patches.txt"]:::module
    end
    subgraph "API Layer"
      WCClient["woocommerce_api.py"]:::module
      Endpoint["endpoint.py"]:::module
      Exceptions["exceptions.py"]:::module
    end
    subgraph "Background Sync Tasks"
      SyncEntry["sync.py"]:::module
      SyncItems["sync_items.py"]:::module
      SyncPrices["sync_item_prices.py"]:::module
      SyncOrders["sync_sales_orders.py"]:::module
      TaskUtils["utils.py"]:::module
    end
    subgraph "Web UI Custom Pages"
      Templates["templates/pages/"]:::module
      PublicAssets["public/"]:::module
    end
    Fixtures["fixtures/custom_field.json"]:::module

    subgraph "Doctypes (Model + Controller + Client)"
      subgraph "WooCommerce Server"
        WCSrvJSON["item_woocommerce_server.json"]:::module
        WCSrvPy["item_woocommerce_server.py"]:::module
      end
      subgraph "Settings"
        SettingsJSON["woocommerce_settings.json"]:::module
        SettingsPy["woocommerce_settings.py"]:::module
        SettingsJS["woocommerce_settings.js"]:::module
      end
      subgraph "Products"
        ProdJSON["woocommerce_product.json"]:::module
        ProdPy["woocommerce_product.py"]:::module
        ProdJS["woocommerce_product.js"]:::module
      end
      subgraph "Orders"
        OrderJSON["woocommerce_order.json"]:::module
        OrderPy["woocommerce_order.py"]:::module
        OrderJS["woocommerce_order.js"]:::module
      end
      subgraph "Request Logs"
        LogJSON["woocommerce_request_log.json"]:::module
        LogPy["woocommerce_request_log.py"]:::module
        LogJS["woocommerce_request_log.js"]:::module
      end
      subgraph "Shipping Rules"
        ShipRuleJSON["woocommerce_server_shipping_rule.json"]:::module
        ShipRulePy["woocommerce_server_shipping_rule.py"]:::module
      end
      subgraph "Field Mapping"
        FieldMapJSON["woocommerce_server_item_field.json"]:::module
        FieldMapPy["woocommerce_server_item_field.py"]:::module
      end
      subgraph "Order Status"
        OrderStatusJSON["woocommerce_server_order_status.json"]:::module
        OrderStatusPy["woocommerce_server_order_status.py"]:::module
      end
    end
  end

  %% Data Flows
  WebUI -->|"On-demand Sync / View Logs"| Endpoint
  Endpoint -->|"Uses"| WCClient
  Scheduler -->|"Triggers"| SyncEntry
  SyncEntry --> SyncItems
  SyncEntry --> SyncPrices
  SyncEntry --> SyncOrders
  SyncItems -->|"Calls"| WCClient
  SyncPrices -->|"Calls"| WCClient
  SyncOrders -->|"Calls"| WCClient
  WCClient -->|"HTTP Requests"| WCAPI
  WCAPI -->|"JSON Response"| WCClient
  WCClient -->|"Returns Data"| SyncItems
  WCClient -->|"Returns Data"| SyncPrices
  WCClient -->|"Returns Data"| SyncOrders
  SyncItems -->|"Create/Update"| ORM
  SyncPrices -->|"Create/Update"| ORM
  SyncOrders -->|"Create/Update"| ORM
  Endpoint -->|"Log Errors"| Exceptions
  Exceptions -->|"Write to"| ORM
  WebUI -->|"CRUD"| ORM

  %% CI/CD Flow
  CI --> Hooks
  CI --> SyncEntry

  %% Click Events
  click Hooks "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/hooks.py"
  click ModulesTxt "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/modules.txt"
  click PatchesTxt "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/patches.txt"
  click WCClient "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/woocommerce_api.py"
  click Endpoint "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/endpoint.py"
  click Exceptions "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/exceptions.py"
  click SyncEntry "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/tasks/sync.py"
  click SyncItems "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/tasks/sync_items.py"
  click SyncPrices "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/tasks/sync_item_prices.py"
  click SyncOrders "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/tasks/sync_sales_orders.py"
  click TaskUtils "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/tasks/utils.py"
  click Templates "https://github.com/mrpondi/woocommerce_conduit/tree/develop/woocommerce_conduit/templates/pages/"
  click PublicAssets "https://github.com/mrpondi/woocommerce_conduit/tree/develop/woocommerce_conduit/public/"
  click Fixtures "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/fixtures/custom_field.json"
  click WCSrvJSON "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/woocommerce_conduit/doctype/item_woocommerce_server/item_woocommerce_server.json"
  click WCSrvPy "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/woocommerce_conduit/doctype/item_woocommerce_server/item_woocommerce_server.py"
  click SettingsJSON "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/woocommerce_conduit/doctype/woocommerce_settings/woocommerce_settings.json"
  click SettingsPy "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/woocommerce_conduit/doctype/woocommerce_settings/woocommerce_settings.py"
  click SettingsJS "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/woocommerce_conduit/doctype/woocommerce_settings/woocommerce_settings.js"
  click ProdJSON "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/woocommerce_conduit/doctype/woocommerce_product/woocommerce_product.json"
  click ProdPy "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/woocommerce_conduit/doctype/woocommerce_product/woocommerce_product.py"
  click ProdJS "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/woocommerce_conduit/doctype/woocommerce_product/woocommerce_product.js"
  click OrderJSON "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/woocommerce_conduit/doctype/woocommerce_order/woocommerce_order.json"
  click OrderPy "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/woocommerce_conduit/doctype/woocommerce_order/woocommerce_order.py"
  click OrderJS "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/woocommerce_conduit/doctype/woocommerce_order/woocommerce_order.js"
  click LogJSON "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/woocommerce_conduit/doctype/woocommerce_request_log/woocommerce_request_log.json"
  click LogPy "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/woocommerce_conduit/doctype/woocommerce_request_log/woocommerce_request_log.py"
  click LogJS "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/woocommerce_conduit/doctype/woocommerce_request_log/woocommerce_request_log.js"
  click ShipRuleJSON "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/woocommerce_conduit/doctype/woocommerce_server_shipping_rule/woocommerce_server_shipping_rule.json"
  click ShipRulePy "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/woocommerce_conduit/doctype/woocommerce_server_shipping_rule/woocommerce_server_shipping_rule.py"
  click FieldMapJSON "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/woocommerce_conduit/doctype/woocommerce_server_item_field/woocommerce_server_item_field.json"
  click FieldMapPy "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/woocommerce_conduit/doctype/woocommerce_server_item_field/woocommerce_server_item_field.py"
  click OrderStatusJSON "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/woocommerce_conduit/doctype/woocommerce_server_order_status/woocommerce_server_order_status.json"
  click OrderStatusPy "https://github.com/mrpondi/woocommerce_conduit/blob/develop/woocommerce_conduit/woocommerce_conduit/doctype/woocommerce_server_order_status/woocommerce_server_order_status.py"

  %% Styles
  classDef core fill:#D0E6FF,stroke:#0366d6,color:#000
  classDef module fill:#DFF2BF,stroke:#4F8A10,color:#000
  classDef external fill:#FFE0B2,stroke:#E65100,color:#000
```
