Architecture
How the theme's parts fit together, who owns each value, and where things break.
| Page | Question it answers |
|---|---|
| Build pipeline | How does TypeScript in src/ end up on the storefront? |
| Liquid to JavaScript contract | How does Liquid data reach the browser code? |
| Mini-cart | How does the cart drawer stay in step with Shopify and with other apps? |
| Medispa booking | How does a treatment booking become a cart line? |
| Popup system | How does the theme decide which popup a shopper sees? |
The shape of the system
This is a Shopify theme. Shopify owns page rendering, the cart, checkout and customer accounts, and the theme cannot change how any of them work. The theme adds browser code that reacts to the shopper and calls Shopify's storefront APIs.
The repository has no server and no database. All state lives in one of four places:
| State | Owner | Editable by |
|---|---|---|
| Theme and section settings | config/settings_data.json in the published theme | Store staff, in the theme editor |
| Product and page metafields | Shopify | Store staff, in Shopify admin |
| Metaobject entries | Shopify | Store staff, under Content > Metaobjects |
| Cart contents | Shopify | The shopper, through the storefront cart API |
Liquid renders everything else a page needs into the HTML, or the browser fetches it from a third-party service.
Trust boundaries
Everything in src/ runs in the shopper's browser, and the shopper can read all of it. No secret belongs in a src/
file, a section schema or a theme setting, because the storefront exposes all three.
The GitHub Actions theme pull workflow uses a Shopify CLI theme token. It is stored as a repository secret, never appears in theme files, and is the only credential connected to this repository.
Third-party scripts on the storefront, such as Klaviyo, Sesami, review widgets and the wishlist app, run with the same
access as theme code. A faulty app script can break theme code. Apps have also written to the cart without announcing
it, which is why the mini-cart patches window.fetch to detect those writes.
Failure modes that recur
A third-party script is blocked or slow. The booking calendar waits for the Sesami SDK before rendering, so an ad blocker leaves an empty placeholder and no error. Popups also fail to appear when Klaviyo does not load.
An app writes to the cart without telling the theme. The mini-cart's fetch interceptor handles this. See Mini-cart.
Someone edits a generated file by hand. snippets/vite-tag.liquid and src/entrypoints/theme.styles.css are build
output committed to git. The next build overwrites a hand edit. See Build pipeline.
A theme pull overwrites local work. The GitHub Actions workflow pulls the live theme into the production branch on
a schedule. Settings changed in the theme editor reach git this way, and so do edits made in Shopify's code editor. See
Deploy and roll back.