🏛️ SearchAtlas Shopify Add-on: Architecture Overview for Developers
Understanding how the SearchAtlas Shopify Add-on is structured under the hood is essential for developers who need to maintain the codebase, build extensions, debug production issues, or audit data flows. This article breaks down every core component, explains how they interact, and maps the complete data flow from installation to pixel firing. 🔍
🔄 High-Level Flow
At a high level, the add-on follows a linear setup and activation flow that connects the Shopify store to the SearchAtlas backend. Here is how each stage connects:
🔄 Step 1 — Install: The merchant installs the app, triggering the OAuth flow. The app stores the shop identifier and access token securely. Note that the connection experience is driven by the Connector Gateway API (CGW), which provides a unified frontend UI for both OAuth and API-key authentication types. Developers building or debugging the connection flow should treat the Connector Gateway as the source of truth for connection state and auth handshakes.
🔄 Step 2 — Enable OTTO Pixel: The merchant toggles the pixel on from the Settings UI. The app then chooses an injection method based on the active theme: if the storefront is running an Online Store 2.0 compatible theme, the app activates a theme app embed; if the theme is a legacy or non-OS 2.0 theme, the app falls back to registering a ScriptTag via the Shopify ScriptTag API. Developers can predict the path by checking the theme's OS 2.0 compatibility flag via the Shopify Themes API before debugging which injection method was used.
🔄 Step 3 — Pixel Active: The OTTO Pixel loads on every storefront page. The SearchAtlas backend can now detect, validate, and deploy OTTO-powered SEO fixes. Note that OTTO AI recommendations are generated via an AI model routing layer — requests are routed through OpenRouter to Gemini Flash Lite. Developers debugging the recommendation generation pipeline should be aware that latency, rate limits, and prompt behavior are influenced by this routing layer.
🔄 Step 4 — Diagnostics: The merchant or agency runs a diagnostic scan from the admin UI. At a high level, the app makes an authenticated request to the SearchAtlas Diagnostics API with the shop context, processes the structured response, and surfaces results in the admin UI. This article describes the diagnostics step at a high level — for the full endpoint specification, request payload schema, and response structure, refer to the SearchAtlas Diagnostics API reference documentation.
🔄 Step 5 — Uninstall: If the merchant removes the app, a webhook triggers cleanup — ScriptTags are removed and the project is marked as paused in SearchAtlas. A paused project means: project data is retained (not deleted), active OTTO SEO fixes are no longer served because the pixel is gone, but recommendations and historical data are preserved. On reinstall, the project can be resumed without data loss by re-linking the shop identifier to the existing project.
🧩 Core Components
The add-on is composed of five distinct components, each with a specific responsibility. Understanding what each component does helps you know where to look when debugging or extending the system. The five components are: the Admin App (Remix), the Theme App Extension, the ScriptTag API Injector, the Diagnostics Engine, and the Webhooks layer. The Admin App orchestrates everything: it handles OAuth, drives the Settings UI, and decides whether the Theme App Extension or the ScriptTag API Injector is used to deploy the pixel. The Diagnostics Engine runs validation against the live pixel regardless of which injection method was used, and the Webhooks layer keeps the data store and SearchAtlas project state in sync with Shopify lifecycle events.
🖥️ Admin App (Remix)
🖥️ This is the central control plane of the add-on. It handles OAuth authentication, renders the Settings UI, processes diagnostic requests, displays the log viewer, and processes the app uninstall webhook.
🖥️ Located in the /app/routes/settings.* directory in the Remix project structure.
🎨 Theme App Extension (Online Store 2.0)
🎨 This is the preferred pixel injection method for any Shopify store running an Online Store 2.0 compatible theme.
🎨 The app embed inserts the OTTO Pixel script directly into the page head globally — merchants can enable or disable it from Customize Theme → App Embeds without touching any code.
🎨 Optional app blocks provide per-template control for merchants who need more granular placement.
📜 ScriptTag API Injector (Fallback / Legacy Themes)
📜 For stores running older or custom themes that do not support Online Store 2.0, the ScriptTag API injector automatically registers a hosted JavaScript file to load on every storefront page.
📜 This method requires no code edits from merchants but is considered a legacy fallback — the theme app extension should always be preferred when available.
🩺 Diagnostics Engine
🩺 The Diagnostics Engine is responsible for validating that the OTTO Pixel is correctly installed and functioning. It communicates with the SearchAtlas API and performs several automated checks.
🩺 Duplicate pixel detection — identifies cases where the pixel fires more than once per page load.
🩺 CSP / blocked script checks — detects Content Security Policy rules that may be preventing the pixel from loading.
🩺 UUID mismatch checks — verifies that the pixel identifier matches the expected project configuration in SearchAtlas.
🔗 Webhooks
🔗 The add-on listens for two key Shopify webhook events that affect pixel state and project status.
🔗 app/uninstalled — triggers removal of all registered ScriptTags and marks the associated SearchAtlas project as paused.
🔗 Theme publish/update — triggers a re-validation of the theme app embed state to confirm the pixel is still active after a theme change.
⚠️ Do Not Manually Inject the OTTO Pixel
⚠️ Important: Merchants and developers should not manually paste the OTTO Pixel script into Shopify theme files (theme.liquid, layout files, or any template). Manual injection is unsupported and has been observed to cause 9+ theme errors, conflicts with the official ScriptTag/Theme App Embed injection paths, and duplicate pixel firing that breaks diagnostics.
⚠️ The only supported installation paths are: (1) toggling the pixel on via the app's Settings UI, which automatically uses the ScriptTag API or theme app embed depending on the theme, or (2) enabling the app embed from Customize Theme → App Embeds for Online Store 2.0 themes.
⚠️ If automated installation fails or you need assisted installation, contact SearchAtlas support rather than editing theme files. Support can verify the connection, manually register the ScriptTag, or assist with theme app embed activation.
🛠️ Troubleshooting: OAuth & Connection Failures
🛠️ OAuth token exchange failures — If the Shopify store connection fails during the install or reinstall flow, the most common causes are: an interrupted OAuth handshake, expired or revoked access tokens, or DNS resolution errors when the Connector Gateway attempts to reach the shop's myshopify.com domain.
🛠️ DNS resolution errors — In rare cases, the backend cannot resolve the Shopify domain during the token exchange. This typically surfaces as a generic connection error in the Connections UI. A retry after a few minutes resolves most transient DNS issues.
🛠️ If self-service reinstallation does not resolve the issue, contact SearchAtlas support for backend-assisted connection. Support can manually complete the token exchange, verify the Connector Gateway state, and link the shop to the correct SearchAtlas project without requiring the merchant to repeat the OAuth flow.
🗄️ Data Store
The add-on persists a small but critical set of data to support pixel management, diagnostics, and session continuity. The following fields are stored per shop:
🗄️ Shop identifier and access token — stored securely after OAuth completion to authenticate all subsequent API calls to Shopify.
🗄️ Pixel status — whether the OTTO Pixel is currently enabled or disabled for the store.
🗄️ Last diagnostic date — timestamp of the most recent diagnostics scan result.
🗄️ ScriptTag IDs — stored so they can be cleaned up accurately on uninstall or when switching to a theme app embed.
🗄️ Theme extension IDs — stored to track and re-validate embed state when themes are published or updated.
📊 Simplified Data Flow Summary
📊 Install: Store shop and access_token after OAuth completes.
📊 Enable Pixel: Create ScriptTag OR activate theme app embed → store the resulting IDs.
📊 Run Diagnostics: Hit SearchAtlas API with shop context → return structured results to the admin UI.
📊 Uninstall: Receive webhook → delete ScriptTags → mark SearchAtlas project as paused.
💡 Architecture Best Practices
💡 Always use the theme app extension as the primary injection method — it is more resilient to theme updates and does not require merchant code edits.
💡 Store ScriptTag and extension IDs at creation time — without them, cleanup on uninstall becomes unreliable and can leave orphaned scripts on the storefront.
💡 Handle the theme publish webhook — theme updates can silently disable app embeds; re-validating on publish prevents silent pixel loss in production.