# shopify/shopify-api-js architecture

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

- Interactive diagram: https://gitdiagram.com/shopify/shopify-api-js
- Repository: https://github.com/shopify/shopify-api-js

## Overview

##### Project type and purpose
- This is an open-source monorepo containing several JavaScript/TypeScript libraries and utilities for building Shopify apps.
- It is *not* a single end-user application but a suite of API client libraries (`@shopify/shopify-api`, `@shopify/storefront-api-client`, `@shopify/admin-api-client`, `@shopify/graphql-client`) plus a GraphQL codegen preset (`@shopify/api-codegen-preset`).

##### File structure
- Top‐level configurations: `turbo.json`, `tsconfig*.json`, `.github/workflows/*`, `package.json` – orchestrate builds, tests, and releases.
- `packages/`: each subfolder is an independently built, tested, and published npm package.
- Within each package:
- `src/` holds the source modules (e.g. `auth/`, `clients/`, `graphql-client/`, `rest/`, `adapters/`).
- `tests/` or `__tests__/` contain Jest test suites.
- Build configs (`babel.config.json`, `rollup.config.*`, `tsconfig.*.json`).
- `packages/shopify-api/adapters/`: adapter pattern for different runtimes (Node, Cloudflare Worker, mock, web).

##### README for insights
- Describes the purpose of each package.
- Emphasizes server use (`@shopify/shopify-api`, `@shopify/admin-api-client`) vs. client/server flexibility (`@shopify/storefront-api-client`) vs. generic GraphQL client (`@shopify/graphql-client`) vs. codegen (`@shopify/api-codegen-preset`).

##### Main components
a. **Monorepo infrastructure**
- Turbo build orchestrator
- GitHub Actions CI/CD pipelines (lint, test, release)
b. **Packages (modules)**
- shopify-api: OAuth, Admin API (REST/GraphQL), webhooks, billing, session management
- admin-api-client: REST & GraphQL Admin API wrapper
- storefront-api-client: GraphQL Storefront API wrapper
- graphql-client: generic GraphQL client utilities
- api-codegen-preset: GraphQL codegen plugin
c. **Adapters** (inside `shopify-api`)
- Node, Cloudflare Worker, web-api, mock – abstracting HTTP transport and environment
d. **Build & Test Tools**
- Babel + Rollup pipelines
- TypeScript compilation
- Jest test runner
e. **External Services**
- Shopify Admin API endpoints (REST/GraphQL)
- Shopify Storefront API (GraphQL)
- npm registry (for package publishing)

##### Relationships and data flows
- **Developer workflow**:
Developer → Monorepo root → selects/edits package → build/test → publishes to npm
- **Runtime flow**:
Application code → calls library (e.g. `@shopify/shopify-api` or `@shopify/storefront-api-client`) → adapter → HTTP request → Shopify API → JSON/GraphQL response → library parses → returns to application
- **Codegen flow**:
Source `#graphql` tags → processed by `api-codegen-preset` in build pipeline → generates typed documents consumed by GraphQL clients

##### Architectural patterns and design principles
- **Monorepo + modular packages**: independent versioning, clear boundaries
- **Adapter pattern** for environment-specific HTTP transport
- **Separation of concerns**: auth, client operations, validations, codegen
- **Type safety** via TypeScript and generated GraphQL types

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo Infrastructure
    subgraph "Monorepo Infrastructure"
        direction TB
        Infra_Turbo["Turbo Build Orchestrator"]:::infra
        Infra_CICD["CI/CD Pipelines"]:::infra
        Infra_PackageJSON["Root package.json"]:::infra
    end

    %% Packages
    subgraph "Packages" 
        direction TB
        subgraph "@shopify/shopify-api" 
            direction TB
            API_Index["index.ts"]:::pkg
            API_Auth["Auth Module"]:::pkg
            API_OAuth["OAuth Submodule"]:::pkg
            API_Admin_GQL["Admin GraphQL Client"]:::pkg
            API_Admin_REST["Admin REST Client"]:::pkg
            API_Webhooks["Webhooks"]:::pkg
            API_Billing["Billing"]:::pkg
            API_Session["Session Management"]:::pkg
            API_Utils["Core Utils & Types"]:::pkg

            subgraph "Adapters" 
                direction TB
                Adapter_Node["Node Adapter"]:::adapter
                Adapter_CF["Cloudflare Worker Adapter"]:::adapter
                Adapter_Web["Web API Adapter"]:::adapter
                Adapter_Mock["Mock Adapter"]:::adapter
            end
        end

        Admin_Client["@shopify/admin-api-client"]:::pkg
        Storefront_Client["@shopify/storefront-api-client"]:::pkg
        GraphQL_Client["@shopify/graphql-client"]:::pkg
        Codegen_Preset["@shopify/api-codegen-preset"]:::pkg
    end

    %% Build & Test Tools
    subgraph "Build & Test Tools"
        direction TB
        Tool_Babel["Babel Configs"]:::tool
        Tool_Rollup["Rollup Configs"]:::tool
        Tool_TS["TypeScript Configs"]:::tool
        Tool_Jest["Jest Configs"]:::tool
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Ext_AdminAPI["Shopify Admin API"]:::external
        Ext_StorefrontAPI["Shopify Storefront API"]:::external
        Ext_NPM["npm Registry"]:::external
    end

    %% Developer Workflow
    Dev["Developer"]:::actor
    Dev -->|"edits/selects package"| Infra_Turbo
    Infra_Turbo -->|"orchestrates build/test"| Tool_TS
    Tool_TS --> Tool_Babel
    Tool_Babel --> Tool_Rollup
    Tool_Rollup --> Tool_Jest
    Tool_Jest -->|"publishes"| Ext_NPM

    %% Package Dependencies & Flows
    Codegen_Preset -->|"generates types"| GraphQL_Client
    GraphQL_Client -->|"used by"| Storefront_Client
    GraphQL_Client -->|"used by"| Admin_Client

    API_Index --> API_Auth
    API_Auth --> API_OAuth
    API_Index --> API_Admin_GQL
    API_Index --> API_Admin_REST
    API_Index --> API_Webhooks
    API_Index --> API_Billing
    API_Index --> API_Session
    API_Index --> API_Utils

    API_Index --> Adapter_Node
    API_Index --> Adapter_CF
    API_Index --> Adapter_Web
    API_Index --> Adapter_Mock

    Adapter_Node -->|"HTTP Request"| Ext_AdminAPI
    Adapter_CF -->|"HTTP Request"| Ext_AdminAPI
    Adapter_Web -->|"HTTP Request"| Ext_AdminAPI
    Adapter_Mock -->|"simulates"| API_Index

    Storefront_Client -->|"requests"| Ext_StorefrontAPI
    Admin_Client -->|"requests"| Ext_AdminAPI

    %% Click Events
    click Infra_Turbo "https://github.com/shopify/shopify-api-js/blob/main/turbo.json"
    click Infra_CICD "https://github.com/shopify/shopify-api-js/tree/main/.github/workflows/"
    click Infra_PackageJSON "https://github.com/shopify/shopify-api-js/blob/main/package.json"
    click API_Index "https://github.com/shopify/shopify-api-js/blob/main/packages/shopify-api/lib/index.ts"
    click API_Auth "https://github.com/shopify/shopify-api-js/tree/main/packages/shopify-api/lib/auth/"
    click API_OAuth "https://github.com/shopify/shopify-api-js/tree/main/packages/shopify-api/lib/auth/oauth/"
    click API_Admin_GQL "https://github.com/shopify/shopify-api-js/tree/main/packages/shopify-api/lib/clients/admin/graphql/"
    click API_Admin_REST "https://github.com/shopify/shopify-api-js/tree/main/packages/shopify-api/lib/clients/admin/rest/"
    click API_Webhooks "https://github.com/shopify/shopify-api-js/tree/main/packages/shopify-api/lib/webhooks/"
    click API_Billing "https://github.com/shopify/shopify-api-js/tree/main/packages/shopify-api/lib/billing/"
    click API_Session "https://github.com/shopify/shopify-api-js/tree/main/packages/shopify-api/lib/session/"
    click API_Utils "https://github.com/shopify/shopify-api-js/tree/main/packages/shopify-api/lib/utils/"
    click Adapter_Node "https://github.com/shopify/shopify-api-js/tree/main/packages/shopify-api/adapters/node/"
    click Adapter_CF "https://github.com/shopify/shopify-api-js/tree/main/packages/shopify-api/adapters/cf-worker/"
    click Adapter_Web "https://github.com/shopify/shopify-api-js/tree/main/packages/shopify-api/adapters/web-api/"
    click Adapter_Mock "https://github.com/shopify/shopify-api-js/tree/main/packages/shopify-api/adapters/mock/"
    click Admin_Client "https://github.com/shopify/shopify-api-js/blob/main/packages/admin-api-client/package.json"
    click Storefront_Client "https://github.com/shopify/shopify-api-js/blob/main/packages/storefront-api-client/package.json"
    click GraphQL_Client "https://github.com/shopify/shopify-api-js/blob/main/packages/graphql-client/package.json"
    click Codegen_Preset "https://github.com/shopify/shopify-api-js/blob/main/packages/api-codegen-preset/package.json"
    click Tool_Babel "https://github.com/shopify/shopify-api-js/blob/main/packages/admin-api-client/babel.config.json"
    click Tool_Rollup "https://github.com/shopify/shopify-api-js/blob/main/packages/graphql-client/rollup.config.cjs"
    click Tool_TS "https://github.com/shopify/shopify-api-js/blob/main/tsconfig.json"
    click Tool_Jest "https://github.com/shopify/shopify-api-js/blob/main/packages/shopify-api/jest.config.ts"

    %% Styles
    classDef infra fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef pkg fill:#d4edda,stroke:#28a745,color:#000;
    classDef adapter fill:#fff3cd,stroke:#ffecb5,color:#000;
    classDef tool fill:#e2e3e5,stroke:#6c757d,color:#000;
    classDef external fill:#ffe5b4,stroke:#ff9900,color:#000;
    classDef actor fill:#f5c6cb,stroke:#dc3545,color:#000;
```
