Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 55 ยท Orientation

App Architecture at a Glance

See how a Shopify app fits together: the embedded admin app, your backend, extensions, webhooks and Shopify as the source of truth, with a request-flow diagram.

Before you write code, it helps to know where each piece of an app runs and who talks to whom. Shopify apps look intimidating at first because several things happen in several places: a page inside the admin, a server on the internet, small programs running on Shopify's side, and events arriving at your server when nobody is looking at the screen.

This lesson draws the whole map. You will learn the five building blocks, follow one merchant click from the browser to the database and back, and see which parts run on Shopify and which run on your server. A runnable simulator at the end lets you trace three different flows. The simulator is a stand-in: it models the shape of the real traffic, but no Shopify service is involved.

The five building blocks

  1. The embedded app (frontend). Pages that appear inside an iframe in the Shopify admin. They are normal web pages: with the standard template they are React routes served by your own server. The merchant never leaves the admin.
  2. Your backend. The server that serves those pages and also handles requests from Shopify. It authenticates the merchant, calls the Admin API, and reads and writes your database.
  3. Extensions. Small programs or UI pieces you upload with the CLI. They run on Shopify: in the theme, the checkout, the admin, POS or customer accounts. They can call back to your backend when they need data you own.
  4. Webhooks. HTTP requests that Shopify sends to your server when something happens (an order is created, a product changes, your app is uninstalled).
  5. Shopify itself. The platform holds the merchant's products, orders, customers and inventory. It is the source of truth for that data.

The last point shapes good design. If you copy products into your own database, your copy can drift from reality: a merchant edits a price in the admin and your copy is stale. Prefer reading from Shopify when you need current store data, and keep only what you need in your own database (your settings, your logs, derived data). When you must cache, update the cache from webhooks and reconcile it periodically. Shared ideas about webhooks and syncing are covered in Integrations: ERP, PIM, OMS and Marketplaces in the e-commerce track.

flowchart TD
    M["Merchant in the Shopify admin"] --> IF["Embedded app iframe"]
    IF --> BE["Your backend and database"]
    BE -->|"Admin GraphQL API"| SH["Shopify platform<br/>products, orders, customers"]
    SH -->|"Webhooks"| BE
    EXT["Extensions and Functions<br/>run on Shopify"] --> SH
    EXT -.->|"optional calls"| BE
    S["Shopper"] --> EXT

Merchants reach your backend through the iframe; Shopify reaches it through webhooks; extensions run on Shopify.

Follow one click

Suppose a merchant opens your app and presses "Add a note to this product". Here is the usual sequence.

  1. The admin loads your app URL in an iframe. App Bridge, a script Shopify provides, runs inside that page.
  2. Your page needs data, so it sends a request to your backend. App Bridge attaches a session token, a short-lived signed JWT that proves which shop and user is calling. (Chapter 2 builds and verifies one.)
  3. Your backend checks the token. If valid, it finds or obtains an access token for that shop.
  4. Your backend calls the Admin GraphQL API with the access token. Shopify checks the token's scopes and returns data or an error.
  5. Your backend saves the note in your own database, keyed by shop domain and product ID.
  6. The backend responds, and your page updates.

Your backend never sees the merchant's password. It trusts the signed token and Shopify's responses. Every step has a failure mode (token expired, scope missing, rate limit hit), and later chapters cover each one.

What runs where

Component Runs on You deploy it with
Embedded pages, API routes, jobs Your server Your hosting provider
Your database Your infrastructure Your hosting provider
Theme app extensions Shopify (rendered with the theme) shopify app deploy
Checkout, admin, POS UI extensions Shopify (sandboxed) shopify app deploy
Shopify Functions Shopify (WebAssembly sandbox) shopify app deploy
App configuration (URLs, scopes, webhooks) Shopify shopify app deploy

This split has a practical consequence: deploying your server and deploying your app version are two separate acts. Pushing new server code does not publish new extensions, and deploying extensions does not update your server. Deploying Your App returns to this.

Reading the template with this map

The official template is a React Router app. A few real file names help to map the picture onto code (read-only, do not worry about the contents yet):

TEXT
app/shopify.server.js            -> sets up authentication and the Admin API client
app/routes/app._index.jsx        -> an embedded page the merchant sees
app/routes/webhooks.app.uninstalled.jsx -> a webhook handler
extensions/                      -> extensions and functions, deployed to Shopify
shopify.app.toml                 -> configuration that describes the app to Shopify

Names may change between template versions; Creating an App with the CLI tours the actual folders.

A request-flow simulator

The first stand-in replays three flows as lines of "who sends what to whom". The data is invented. What is real is the order of the steps: a merchant request goes through your backend to Shopify, a webhook goes the other way, and a shopper-facing extension never touches your server unless you design it to.

JS Trace three flows through the app

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The volume discount flow never reaches your server. That is why functions are fast and why they cannot, for example, call your database: they receive only the data you asked for in their input query.

A second stand-in: sort the work

When you design a feature, decide for each task whether it belongs on your server, in an extension, or in a function. This tiny classifier writes down the rules of thumb we will keep using.

JS Where should this task live?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Common mistakes to avoid

  • Treating your database as the source of truth for store data. Read current prices and inventory from Shopify; store only what is yours.
  • Doing slow work inside a webhook request. Shopify expects a quick response. Acknowledge fast and process later (Reliable Webhook Handlers).
  • Assuming one server instance. Production runs several instances, so in-memory state is lost. Use a database.
  • Forgetting that every shop is a separate tenant. Your data must always be keyed by shop.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is Shopify called the source of truth for products and orders?

    A copy in your own database can drift when the merchant edits data in the admin. Read from Shopify when you need current data, and keep only what you own.
  2. 2. What does the embedded app send to your backend to prove who is calling?

    App Bridge adds a session token that your backend verifies. It identifies the shop and user without sharing a password.
  3. 3. Which component never needs your server to run?

    Functions run on Shopify in a sandbox, using only the input you request. The others are served or run by your own backend.
  4. 4. You push new server code. Are your extensions updated too?

    Server hosting and the app version are separate. Extensions and configuration reach Shopify through shopify app deploy.

Summary

  • An app has an embedded frontend, a backend, extensions, webhook handlers and Shopify as the source of truth.
  • A merchant request travels iframe, backend, Admin API; webhooks travel the opposite way; shopper-facing extensions and functions run on Shopify.
  • Extensions, functions and configuration are deployed with the CLI; your server is deployed separately.
  • Keep only your own data in your database and key everything by shop.
  • The simulators here are stand-ins that show the shape of the traffic, not real Shopify calls.

Next: Tooling and Setup