product_inventory/docs/ARCHITECTURE.md

Architecture Documentation

System Overview

This project serves as a bridge between Google Sheets and Shopify. It enables a two-way sync (primarily Sheets to Shopify for products) and allows managing inventory directly from a spreadsheet.

Core Flows

1. Product Updates:

   • User edits a cell in the "product_inventory" sheet.
   • onEditQueue trigger fires, capturing the SKU and timestamp.
   • Edits are batched in PropertiesService (script properties).
   • A time-based trigger runs processBatchedEdits every minute.
   • The processing function locks the script, reads the queue, and pushes changes to Shopify via the Admin API.

2. Order Sync:

   • Users can run menu commands to fetch orders from Shopify.
   • The Shop class fetches orders via the REST API, handling pagination.
   • Data is populated into specific sheets (_orders, _line_items, _customer, etc.).

Key Components

1. Queue System (src/onEditQueue.ts)

To avoid hitting Shopify API rate limits and Google Apps Script execution time limits, edits are not processed immediately.

• onEditQueue(e):

  • Triggered on every cell edit.
  • Checks if the edit is valid (correct sheet, valid SKU).
  • Acquires a DocumentLock.
  • Updates a JSON list in ScriptProperties (pendingEdits).
  • Debounces edits (updates timestamp if SKU is already pending).

• processBatchedEdits():

  • Run via time-based trigger (every 1 minute).
  • Acquires a ScriptLock.
  • Reads pendingEdits.
  • Filters for edits older than BATCH_INTERVAL_MS (30s) to allow for multiple quick edits to the same SKU.
  • Iterates through valid edits and calls Product.UpdateShopifyProduct.
  • SKU Validation: Before any action, checks if the SKU is valid (not empty, ?, or n). Aborts if invalid.

2. Product Lifecycle Logic

• Creation:

  • Uses the SKU as the Shopify Handle (URL slug).
  • Prevents creation if the SKU is a placeholder.

• Updates:

  • Prioritizes ID-based lookup.
  • If the shopify_id column is populated, the system trusts this ID to locate the product in Shopify, even if the SKU has changed in the sheet.
  • As a result, changing a SKU in the sheet and syncing will rename the existing product (handle/SKU) rather than creating a duplicate.

2. Shopify Integration (src/shopifyApi.ts)

The project uses a hybrid approach for the Shopify Admin API:

• REST API: Used primarily for fetching Orders (legacy support).

• GraphQL API: Used for fetching and updating Products and Inventory.

• GraphQL API: Used for fetching and updating Products and Inventory.

The Shop class implements the IShop interface, handling authentication using credentials stored in the "vars" sheet. The interface decoupling facilitates robust unit testing via MockShop.

3. Configuration (src/config.ts)

Configuration, including API keys, is stored in a dedicated Google Sheet named "vars". The Config class reads these values at runtime using a vlookup style helper.

Required "vars" columns:

• key: The name of the configuration variable.
• value: The actual value.

4. Global Entry Points (src/global.ts)

Because Webpack bundles the code into an IIFE (Immediately Invoked Function Expression) to avoid global scope pollution, top-level functions defined in modules are not automatically globally accessible in the Apps Script environment.

• Requirement: Any function that needs to be called from the frontend via google.script.run, triggered by a menu, or attached to a spreadsheet event must be explicitly assigned to the global object in src/global.ts.
• Example:

  import { myFunc } from "./myModule"
  ;(global as any).myFunc = myFunc
  

• Rationale: This is the only way for the Google Apps Script runtime to find these functions when they are invoked via the google.script.run API or other entry point mechanisms.

5. Status Automation (src/statusHandlers.ts)

A modular system handles changes to the status column. It uses a registry of StatusHandler implementations:

• Published: Sets Shopify Status ACTIVE, Quantity 1.
• Sold/Artist Swap: Sets Shopify Status ACTIVE, Quantity 0.
• Drafted: Sets Shopify Status DRAFT.

Triggers

Triggers are managed programmatically via src/triggers.ts. Running reinstallTriggers will wipe existing project triggers and set up the standard set:

• onEdit -> onEditHandler (Main Router)
• TimeBased (1 min) -> processBatchedEdits
• TimeBased (10 min) -> checkRecentSales

5. Troubleshooting Panel (src/sidebar.ts, src/Sidebar.html)

A dedicated side panel provides visibility into the background queue system.

• Backend (src/sidebar.ts):

  • getQueueStatus(): Returns the current state of the queue and global toggle.
  • setQueueEnabled(): Toggles the global queueEnabled script property.
  • deleteEdit() / pushEdit(): Manages specific items in the queue with safety checks.

• Frontend (src/Sidebar.html):

  • Displays pending edits with timestamps.
  • Provides controls to globally enable/disable processing.
  • Allows manual intervention (delete/push) for individual items.

6. Service Layer, Testing & Quality

To enable unit testing without Google Apps Script dependencies, the project uses a Service pattern with Dependency Injection.

Architecture

• ISpreadsheetService: Interface for all sheet interactions.
• GASSpreadsheetService: Production implementation wrapping SpreadsheetApp.
• MockSpreadsheetService: In-memory implementation for tests.

Quality Assurance

We use Husky and lint-staged to enforce quality standards at the commit level:

1. Pre-commit Hook: Automatically runs npm test -- --onlyChanged --coverage.
2. Coverage Policy: Any file modified in a commit must meet an 80% line coverage threshold. This ensures the codebase quality improves monotonically ("Boy Scout Rule").

Classes (like Product) should accept an ISpreadsheetService in their constructor. This allows providing the Mock service during tests to verify logic without touching real Google Sheets.

7. Media Manager (src/mediaHandlers.ts, src/MediaSidebar.html)

We implemented a "Sidebar-First" architecture for product media to handle the complexity of Google Picker and Shopify Sync.

Frontend (MediaSidebar.html)

• Glassmorphism UI: Uses modern CSS for a premium feel.
• Polling: Since the sidebar can't listen to Sheet events directly efficiently, it polls getMediaState(sku) to detect when the user selects a different product row.
• Google Picker API:
  • Uses the New Google Photos Picker (Session-based) for selecting photos.
  • Uses the Google Drive Picker (Legacy) for selecting existing Drive files.
  • Handles OAuth token passing securely from the server side (google.script.run).

Backend (mediaHandlers.ts)

• Import Strategy:
  • Safe Zone: Files are first downloaded/copied to the Drive Root to ensure we have the asset.
  • Move: Then they are moved to the organized SKU folder (/Product Photos/[SKU]/).
  • Resilience: The file creation logic tries multiple methods (Standard DriveApp, Sanitized Blob, Advanced Drive API) to handle the notoriously fickle nature of UrlFetchApp blobs.
• Shopify Sync:
  • MediaService manages the state.
  • Calculates checksums to avoid re-uploading duplicate images.
  • Uses Shopify's "Staged Uploads" -> "Create Media" mutation flow.

8. Apps Script & HTML Service Constraints

When working with HtmlService (client-side code), the environment differs significantly from the server-side V8 runtime.

1. Server-Side (.ts/.gs):

   • Runtime: V8 Engine.
   • Syntax: Modern ES6+ (Classes, Arrow Functions, const/let) is fully supported.
   • Recommendation: Use standard TypeScript patterns.

2. Client-Side (.html served via createHtmlOutputFromFile):

   • Runtime: Legacy Browser Environment / Strict Caja Sanitization.
   • Constraint: The parser often chokes on ES6 class syntax and complex template strings inside HTML attributes.
   • Rule 1: NO ES6 CLASSES. Use ES5 function constructors and prototype methods.
   • Rule 2: NO Complex Template Strings in Attributes. Do not use src="${var}" if the variable contains a URL. Use document.createElement and set properties (e.g., element.src = value) programmatically.
   • Rule 3: Unified Script Tags. Consolidate scripts into a single block where possible to avoid parser merge errors.
   • Rule 4: Var over Let/Const. Top-level variables should use var or explicit window assignment to ensure they are accessible to inline HTML handlers (e.g., onclick="handler()").