Shopify NetSuite Connector

internal

integrations Shopify + NetSuite Ecosystem

An integration app that synchronizes orders, inventory levels, and fulfillment statuses bi-directionally between Shopify stores and Oracle NetSuite ERP.

React React Router TypeScript Node.js Shopify Polaris Shopify App Bridge GraphQL Prisma SQLite NetSuite RESTlets Docker AWS ECR Mailgun Sentry

cat architecture.md

Container & Deployment Infrastructure

Packages the Node.js application and Prisma runtime inside a lightweight Linux container image.
Builds and publishes versioned images to a private AWS Elastic Container Registry (ECR).
Runs containerized services configured for production with persistent database volumes.

Embedded Merchant Interface

Delivers an embedded administrative dashboard inside Shopify Admin using Shopify Polaris and App Bridge.
Provides visual management for ERP field mappings, sync intervals, connection credentials, and error logs.
Allows operators to trigger manual on-demand syncs and inspect order transaction metadata.

Authentication & Security

Manages multi-tenant merchant authentication and permission scopes via Shopify OAuth.
Signs and authenticates requests to NetSuite RESTlets using Token-Based Authentication (OAuth 1.0a HMAC-SHA256).
Validates internal queue worker and webhook requests using shared secret HMAC-SHA256 header signatures.

API & Webhook Ingestion

Ingests real-time Shopify webhooks for order creation, app uninstallation, and data compliance.
Applies risk assessment filters to incoming orders, tagging high-risk transactions for manual review.
Exposes authenticated action endpoints to receive fulfillment, internal ID, and inventory updates from worker jobs.

ERP & Store Integration Layer

Queries and mutates Shopify resources via the Shopify GraphQL Admin API.
Executes custom NetSuite RESTlet endpoints to create sales orders, fetch inventory activities, and close orders.
Transforms platform-specific data formats, line items, marketplace identifiers, and shipping methods.

Task Scheduling & Coordination

Schedules automated recurring cron tasks for order polling and inventory changes.
Runs automated reconciliation routines on container startup to capture missed inventory movements.
Aggregates failed sync attempts and triggers periodic error reports.

Asynchronous Job Queue Dispatch

Offloads compute-heavy and rate-sensitive payloads to an external queue microservice.
Dispatches discrete background jobs for single-order syncs, bulk order batches, and full catalog inventory refreshes.
Ensures resilience against third-party ERP rate limits and transient connection failures.

Data Persistence

Persists active merchant sessions, tokens, and OAuth scopes using Prisma ORM with SQLite storage.
Stores NetSuite TBA credentials, account configuration, and synchronization timestamps per connected shop.

Monitoring & Notifications

Captures runtime exceptions and performance telemetry using Sentry integration.
Sends automated transactional error digests and alert emails to administrators via Mailgun.

# Asynchronous Queue Offloading: Decoupling sync execution from HTTP request cycles prevents API timeouts and isolates NetSuite rate limiting by delegating batch processing to a dedicated queue worker.
# Token-Based Authentication (TBA) for ERP Security: Integrating with NetSuite via OAuth 1.0a HMAC-SHA256 signatures eliminates the need to store static administrative passwords and adheres to strict enterprise ERP security standards.
# Embedded Native Admin Experience: Building the UI with Shopify Polaris and App Bridge embeds the configuration workflow directly inside the Shopify admin, ensuring a seamless operator experience without requiring external portal logins.
# Defense-in-Depth HMAC Request Verification: All communications between the core application, webhooks, and worker services are verified using cryptographic HMAC signatures to prevent unauthorized state mutations.