# shopify/unity-buy-sdk architecture

> Architecture diagram of the GitHub repository shopify/unity-buy-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shopify/unity-buy-sdk
- Repository: https://github.com/shopify/unity-buy-sdk

## Overview

##### Main components
- Unity Editor / Build Pipeline
– Assets/Editor: mock loaders, build classes, test utilities
– ExternalDependencyManager plugin (manages platform libs)
- Runtime SDK Core
– Assets/Shopify/Unity/SDK:
- ConnectionLoader / QueryLoader (HTTP GraphQL client)
- BaseLoader & ILoaderProvider (loader abstraction)
- ResponseMergeUtil, Serialization & GraphQL query definitions
- NativeMessage & NativePayment interfaces
- UI Toolkit
– Assets/Shopify/UIToolkit:
- Components (HTTPUtils, RemoteImageLoader, ProductCache)
- ShopControllers (CartController, MultiProductShopController)
- Shops (generic and single‐product prefabs, views, animation assets)
- Native Plugins
– iOS (Assets/Shopify/Plugins/iOS + PluginDependencies/iOSPlugin):
- Swift/Objective‐C bridge (UnityBuySDKPlugin.a, UnityBuyAppController)
- Apple Pay event dispatch, PKPayment serialization
– Android (Assets/Shopify/Plugins/Android/libs):
- AAR libraries for web pay and common logic
- External Services
– Shopify Storefront API (GraphQL endpoint)
– Safari Web View / Chrome Custom Tab for web checkout
– Apple Pay / Android Pay mobile payment networks
- Testing Framework
– Assets/IntegrationTests & Assets/NativeTesting
– UIToolkit tests under Assets/Shopify/UIToolkit/Test
- CI/CD
– .github/workflows (build, test, CLA checks)
– scripts/ (build, test, docs generation, publish)
– Doxygen docs in docs/

##### Relationships & data flows
- Editor layer → (build pipeline) configures & bundles native plugins
- Runtime C# SDK → uses QueryLoader → HTTPUtils → Shopify GraphQL API
- SDK → emits NativeMessage → native plugin modules handle Apple Pay / web checkout
- UI Toolkit controllers → call SDK loaders → update UI views & cache images
- Tests → drive the SDK & UI in Unity Editor or native harness
- CI workflows → execute scripts/**/* → build docs, run tests, package .unitypackage

##### Architectural patterns & principles
- Layered architecture: Editor tools vs Runtime SDK vs UI vs Native
- Abstraction of loader (ILoaderProvider) for pluggable transports (EditorLoader, UnityLoader, NativeLoader)
- MVC‐style separation in UIToolkit: Controllers ↔ Views ↔ Models (Product, Cart)
- GraphQL code generation (scripts/generator) for type‐safe query classes
- CI as code with GitHub Actions for reproducible builds & docs

##### Technologies & frameworks
- Unity (C# / Mono)
- GraphQL (HTTP queries to Shopify API)
- Swift & Objective-C bridging (iOS plugin)
- Android AAR libraries (Chrome Custom Tabs)
- ExternalDependencyManager (Unity package manager plugin)
- Doxygen (native code docs), GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Editor & CI Layer
    subgraph "Editor & CI" 
        direction TB
        EditorPipeline["ShopifyBuildPipeline"]:::editor
        ExternalDepManager["ExternalDependencyManager"]:::editor
        subgraph "CI/CD"
            direction TB
            GitHubActions["GitHub Workflows"]:::editor
            Scripts["scripts/"]:::editor
            Docs["docs/ (Doxygen)"]:::editor
        end
        subgraph "Testing Framework"
            direction TB
            IntegrationTests["IntegrationTests"]:::test
            NativeTesting["NativeTesting"]:::test
            UIToolkitTests["UIToolkit Tests"]:::test
        end
    end

    %% Runtime SDK Core Layer
    subgraph "Runtime SDK Core"
        direction TB
        BaseLoader["BaseLoader"]:::core
        ILoaderProvider["ILoaderProvider"]:::core
        ConnectionLoader["ConnectionLoader"]:::core
        QueryLoader["QueryLoader"]:::core
        ResponseMergeUtil["ResponseMergeUtil"]:::core
        NativeMessage["NativeMessage"]:::core
        NativePayment["NativePayment"]:::core
    end

    %% UI Toolkit Layer
    subgraph "UI Toolkit"
        direction TB
        subgraph "Components"
            direction TB
            HTTPUtils["HTTPUtils"]:::ui
            RemoteImageLoader["RemoteImageLoader"]:::ui
            ProductCache["ProductCache"]:::ui
        end
        subgraph "Controllers"
            direction TB
            CartController["CartController"]:::ui
            MultiProductShopController["MultiProductShopController"]:::ui
            SingleProductShopController["SingleProductShopController"]:::ui
        end
        subgraph "Shops"
            direction TB
            GenericShop["Generic Shop Prefab"]:::ui
            SingleProductShop["Single Product Shop Prefab"]:::ui
            DebugSingleProductShop["DebugSingleProductShop"]:::ui
        end
    end

    %% Native Plugins Layer
    subgraph "Native Plugins"
        direction TB
        subgraph "iOS"
            direction TB
            UnityBuySDKPlugin["UnityBuySDKPlugin (Swift)"]:::native
            UnityBuyAppController["UnityBuyAppController"]:::native
            LibUnityBuySDK["libUnityBuySDKPlugin.a"]:::native
            iOSXcodeProj["UnityBuySDKPlugin.xcodeproj"]:::native
        end
        subgraph "Android"
            direction TB
            CommonAAR["common-unity-release.aar"]:::native
            WebPayAAR["web-pay-unity-release.aar"]:::native
        end
    end

    %% External Services Layer
    ShopifyAPI["Shopify Storefront API"]:::external
    WebCheckout["Safari WebView / Chrome Custom Tab"]:::external
    PaymentNetworks["ApplePay / AndroidPay Networks"]:::external

    %% Connections
    EditorPipeline -->|"build → package"| UnityBuySDKPlugin
    EditorPipeline -->|"build → package"| CommonAAR
    EditorPipeline --> ExternalDepManager

    GitHubActions -->|runs| Scripts
    GitHubActions -->|generates| Docs
    GitHubActions -->|executes tests| IntegrationTests

    QueryLoader -->|"uses"| HTTPUtils
    HTTPUtils -->|"GraphQL Request/Response"| ShopifyAPI
    ConnectionLoader -->|"provides transport"| QueryLoader
    BaseLoader -->|abstracts| ILoaderProvider
    ILoaderProvider -->|implemented by| ConnectionLoader
    ILoaderProvider -->|implemented by| QueryLoader

    NativeMessage -->|"dispatch events"| UnityBuySDKPlugin
    NativeMessage -->|"dispatch events"| WebPayAAR
    NativePayment -->|"serialize payment"| PaymentNetworks

    CartController -->|"calls"| QueryLoader
    MultiProductShopController -->|"calls"| QueryLoader
    SingleProductShopController -->|"calls"| QueryLoader

    CartController -->|"updates UI"| GenericShop
    SingleProductShopController -->|"updates UI"| SingleProductShop
    DebugSingleProductShop -->|"debug view"| CartController

    RemoteImageLoader -->|"fetch images"| ShopifyAPI
    ProductCache -->|"cache images"| RemoteImageLoader

    IntegrationTests -->|drive| QueryLoader
    UIToolkitTests -->|drive| CartController

    %% Click Events
    click EditorPipeline "https://github.com/shopify/unity-buy-sdk/blob/main/Assets/Editor/BuildPipeline/ShopifyBuildPipeline.cs"
    click ExternalDepManager "https://github.com/shopify/unity-buy-sdk/tree/main/Assets/ExternalDependencyManager/Editor"
    click BaseLoader "https://github.com/shopify/unity-buy-sdk/blob/main/Assets/Shopify/Unity/SDK/BaseLoader.cs"
    click ILoaderProvider "https://github.com/shopify/unity-buy-sdk/blob/main/Assets/Shopify/Unity/SDK/ILoaderProvider.cs"
    click ConnectionLoader "https://github.com/shopify/unity-buy-sdk/blob/main/Assets/Shopify/Unity/SDK/ConnectionLoader.cs"
    click QueryLoader "https://github.com/shopify/unity-buy-sdk/blob/main/Assets/Shopify/Unity/SDK/QueryLoader.cs"
    click ResponseMergeUtil "https://github.com/shopify/unity-buy-sdk/blob/main/Assets/Shopify/Unity/SDK/ResponseMergeUtil.cs"
    click NativeMessage "https://github.com/shopify/unity-buy-sdk/blob/main/Assets/Shopify/Unity/SDK/NativeMessage.cs"
    click NativePayment "https://github.com/shopify/unity-buy-sdk/blob/main/Assets/Shopify/Unity/SDK/NativePayment.cs"
    click HTTPUtils "https://github.com/shopify/unity-buy-sdk/blob/main/Assets/Shopify/UIToolkit/Components/HTTPUtils.cs"
    click RemoteImageLoader "https://github.com/shopify/unity-buy-sdk/blob/main/Assets/Shopify/UIToolkit/Components/RemoteImageLoader.cs"
    click ProductCache "https://github.com/shopify/unity-buy-sdk/blob/main/Assets/Shopify/UIToolkit/Components/ProductCache.cs"
    click CartController "https://github.com/shopify/unity-buy-sdk/blob/main/Assets/Shopify/UIToolkit/ShopControllers/Classes/CartController.cs"
    click MultiProductShopController "https://github.com/shopify/unity-buy-sdk/blob/main/Assets/Shopify/UIToolkit/ShopControllers/MultiProductShopController.cs"
    click SingleProductShopController "https://github.com/shopify/unity-buy-sdk/blob/main/Assets/Shopify/UIToolkit/ShopControllers/SingleProductShopController.cs"
    click GenericShop "https://github.com/shopify/unity-buy-sdk/tree/main/Assets/Shopify/UIToolkit/Shops/Generic"
    click SingleProductShop "https://github.com/shopify/unity-buy-sdk/tree/main/Assets/Shopify/UIToolkit/Shops/SingleProduct"
    click DebugSingleProductShop "https://github.com/shopify/unity-buy-sdk/blob/main/Assets/Shopify/UIToolkit/Shops/Debug/DebugSingleProductShop.cs"
    click UnityBuySDKPlugin "https://github.com/shopify/unity-buy-sdk/blob/main/Assets/Shopify/Plugins/iOS/Shopify/UnityBuySDKPlugin.swift"
    click UnityBuyAppController "https://github.com/shopify/unity-buy-sdk/blob/main/Assets/Shopify/Plugins/iOS/Shopify/UnityBuyAppController.mm"
    click LibUnityBuySDK "https://github.com/shopify/unity-buy-sdk/blob/main/Assets/Shopify/Plugins/iOS/Shopify/libUnityBuySDKPlugin.a"
    click iOSXcodeProj "https://github.com/shopify/unity-buy-sdk/blob/main/PluginDependencies/iOSPlugin/UnityBuySDKPlugin.xcodeproj"
    click CommonAAR "https://github.com/shopify/unity-buy-sdk/blob/main/Assets/Shopify/Plugins/Android/libs/common-unity-release.aar"
    click WebPayAAR "https://github.com/shopify/unity-buy-sdk/blob/main/Assets/Shopify/Plugins/Android/libs/web-pay-unity-release.aar"
    click IntegrationTests "https://github.com/shopify/unity-buy-sdk/tree/main/Assets/IntegrationTests"
    click NativeTesting "https://github.com/shopify/unity-buy-sdk/tree/main/Assets/NativeTesting"
    click UIToolkitTests "https://github.com/shopify/unity-buy-sdk/tree/main/Assets/Shopify/UIToolkit/Test"

    %% Styles
    classDef editor fill:#bae1ff,stroke:#000;
    classDef core fill:#baffc9,stroke:#000;
    classDef ui fill:#ffffba,stroke:#000;
    classDef native fill:#ffdfba,stroke:#000;
    classDef external fill:#e2baff,stroke:#000;
    classDef test fill:#ffd1dc,stroke:#000;
```
