shopify-architecture-variants

Shopify Architecture Variants

Overview

Four validated architecture patterns for building on Shopify. Choose based on your use case: embedded admin app, headless storefront, backend integration, or theme extension.

Prerequisites

• Clear understanding of what you're building
• Knowledge of your target merchants
• Understanding of Shopify's app ecosystem

Instructions

Variant A: Embedded Admin App (Remix)

Best for: Admin panel apps, merchant tools, dashboards, order management

When to use: You need to add functionality to the Shopify admin for merchants.

my-shopify-app/
├── app/
│   ├── routes/
│   │   ├── app._index.tsx         # Dashboard (inside Shopify admin)
│   │   ├── app.products.tsx       # Feature pages
│   │   ├── auth.$.tsx             # OAuth handler
│   │   └── webhooks.tsx           # Webhook receiver
│   ├── shopify.server.ts          # @shopify/shopify-app-remix
│   └── root.tsx
├── extensions/                     # Optional extensions
├── prisma/schema.prisma           # Session + app data
├── shopify.app.toml
└── package.json

Key packages: @shopify/shopify-app-remix, @shopify/polaris, @shopify/app-bridge-react

API used: Admin GraphQL API (server-side via authenticate.admin())

Auth: OAuth with session token exchange (handled by the Remix adapter)

// Authenticated loader — runs server-side inside Shopify admin
export async function loader({ request }: LoaderFunctionArgs) {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(`{ shop { name plan { displayName } } }`);
  return json(await response.json());
}

---

Variant B: Headless Storefront (Hydrogen)

Best for: Custom storefronts, unique shopping experiences, PWAs

When to use: You're building a custom frontend that replaces the Shopify Online Store.

my-hydrogen-store/
├── app/
│   ├── routes/
│   │   ├── ($locale)._index.tsx           # Homepage
│   │   ├── ($locale).products.$handle.tsx # Product page
│   │   ├── ($locale).collections._index.tsx
│   │   ├── ($locale).cart.tsx             # Cart page
│   │   └── ($locale).account.tsx          # Customer account
│   ├── components/
│   │   ├── ProductCard.tsx
│   │   ├── Cart.tsx
│   │   └── Header.tsx
│   ├── lib/
│   │   └── shopify.ts                     # Storefront API client
│   └── root.tsx
├── public/
└── hydrogen.config.ts

Key packages: @shopify/hydrogen, @shopify/hydrogen-react, @shopify/remix-oxygen

API used: Storefront GraphQL API (public, no admin tokens needed)

Hosting: Shopify Oxygen (recommended) or any edge platform

// Hydrogen product page — uses Storefront API
export async function loader({ params, context }: LoaderFunctionArgs) {
  const { storefront } = context;
  const { product } = await storefront.query(PRODUCT_QUERY, {
    variables: { handle: params.handle },
  });
  return json({ product });
}

---

Variant C: Backend Integration (Standalone)

Best for: ERP sync, warehouse management, analytics, multi-channel integration

When to use: You're connecting Shopify to other systems — no merchant-facing UI needed.

shopify-integration/
├── src/
│   ├── shopify/
│   │   ├── client.ts              # @shopify/shopify-api client
│   │   ├── webhooks.ts            # Webhook handlers
│   │   └── sync.ts                # Data sync logic
│   ├── services/
│   │   ├── erp-sync.ts            # Sync orders to ERP
│   │   ├── inventory-sync.ts      # Bi-directional inventory
│   │   └── customer-export.ts     # Customer data pipeline
│   ├── jobs/
│   │   ├── daily-sync.ts          # Scheduled sync job
│   │   └── webhook-processor.ts   # Queue-based webhook processing
│   └── index.ts
├── .env
└── package.json

Key packages: @shopify/shopify-api, custom app token

API used: Admin GraphQL API (custom app access token, no OAuth)

Auth: Custom app access token (shpat_xxx) — no OAuth flow needed

// Custom app — direct API access, no merchant UI
const shopify = shopifyApi({
  apiKey: process.env.SHOPIFY_API_KEY!,
  apiSecretKey: process.env.SHOPIFY_API_SECRET!,
  hostName: "localhost",
  apiVersion: "2024-10",
  isCustomStoreApp: true,
  adminApiAccessToken: process.env.SHOPIFY_ACCESS_TOKEN!,
});

---

Variant D: Theme App Extension Only

Best for: Storefront widgets, product reviews, badges, banners

When to use: You only need to add UI elements to the merchant's Online Store.

my-theme-extension/
├── extensions/
│   └── my-widget/
│       ├── blocks/
│       │   ├── product-badge.liquid
│       │   ├── announcement-bar.liquid
│       │   └── review-stars.liquid
│       ├── assets/
│       │   ├── widget.css
│       │   └── widget.js
│       ├── locales/
│       │   └── en.default.json
│       └── snippets/
│           └── shared-styles.liquid
├── shopify.app.toml
└── package.json

Key tech: Liquid templates, JavaScript, CSS

API used: None directly — uses Liquid objects (product, cart, customer)

No server needed: Theme app extensions run entirely in the merchant's storefront.

{% comment %} blocks/product-badge.liquid {% endcomment %}
{% schema %}
{
  "name": "Sale Badge",
  "target": "section",
  "settings": [
    { "type": "text", "id": "badge_text", "label": "Badge Text", "default": "SALE" },
    { "type": "color", "id": "badge_color", "label": "Color", "default": "#FF0000" }
  ]
}
{% endschema %}

{% if product.compare_at_price > product.price %}
  <span class="sale-badge" style="background: {{ block.settings.badge_color }}">
    {{ block.settings.badge_text }}
  </span>
{% endif %}

---

Decision Matrix

Factor	Embedded App	Hydrogen	Backend Integration	Theme Extension
Use case	Admin tools	Custom storefront	System sync	Storefront widgets
Merchant UI	Yes (in admin)	Yes (storefront)	No	Yes (in theme)
API	Admin GraphQL	Storefront GraphQL	Admin GraphQL	Liquid objects
Auth	OAuth	Storefront token	Custom app token	None
Server needed	Yes	Yes	Yes	No
Complexity	Medium	High	Low-Medium	Low
App Store eligible	Yes	N/A	Yes (custom apps)	Yes
Time to build	2-4 weeks	4-8 weeks	1-2 weeks	Days

Output

• Architecture variant selected based on requirements
• Project structure and key packages identified
• Authentication strategy determined
• Technology stack defined

Error Handling

Issue	Cause	Solution
"Should I use Hydrogen?"	Want custom storefront	Yes if replacing Online Store, no if adding to admin
"Embedded vs standalone?"	Need merchant UI?	Embedded = yes. Standalone = backend-only
"Theme extension limits?"	Too complex for Liquid	Combine: extension for UI + embedded app for logic
Over-engineering	Started with microservices	Start with Variant A or C, evolve when needed

Examples

Quick Start by Variant

# Variant A: Embedded Remix App
shopify app init --template remix

# Variant B: Hydrogen Storefront
npm create @shopify/hydrogen

# Variant C: Backend Integration
mkdir shopify-sync && cd shopify-sync
npm init -y && npm install @shopify/shopify-api dotenv

# Variant D: Theme Extension
shopify app init
shopify app generate extension --type theme

Resources

• Shopify App Types
• Hydrogen Framework
• Theme App Extensions
• Custom Apps

Next Steps

For common anti-patterns, see shopify-known-pitfalls.