# gadget-inc/js-clients architecture

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

- Interactive diagram: https://gitdiagram.com/gadget-inc/js-clients
- Repository: https://github.com/gadget-inc/js-clients

## Overview

##### Main Components
- Monorepo Structure and Tooling:
– The repository is managed as a monorepo using tools like PNPM (see pnpm-lock.yaml and pnpm-workspace.yaml) to manage multiple packages. This central management is key for handling versioning, dependency resolution, and cross-package integrations.
– There are shared scripts, configurations (eslintrc, prettier, flake.nix, tsconfig files), and CI/CD pipelines (GitHub workflows and actions) that apply across the repository.

- Core Packages:
– API Client Core: Under packages/api-client-core, this library contains the heart of the client functionality. It provides helper functions, types, and exchange logic that are used across different generated clients. It also sets up the operations (building and running queries, mutations, live queries) and handles internal model management.
– React Bindings: Under packages/react, this package contains the React-specific integrations for Gadget. It exposes components such as GadgetProvider, auto forms, auto tables, authentication components, hooks (useAction, useFetch, useFindOne, etc.) and a wide range of auto-generated modules for integration with React.
– Shopify Integration Libraries:
▪ React Shopify App Bridge: Located in packages/react-shopify-app-bridge, it provides React components tailored to Shopify’s App Bridge. It integrates Gadget’s backend functionality with Shopify’s ecosystem.
▪ Shopify Extensions: Located in packages/shopify-extensions, it contains utilities for working with Shopify UI extensions (both React and plain JavaScript).
– Additional Packages:
– There are example projects (e.g., packages/blog-example) demonstrating usage.
– Other utility or testing packages, such as the test-bundles used to verify output or a tiny GraphQL query compiler (packages/tiny-graphql-query-compiler).

##### Relationships and Interactions
- The React package exposes UI components and hooks; these components may further consume the core functions as well as interfaces from both the API Client Core and potentially from Shopify Extensions if integration with Shopify is needed.
- The monorepo also includes CI/CD pipelines (workflows under .github/workflows and actions) that govern automated testing and releases. These should be represented as supporting infrastructure that interconnects with all packages.

##### Architectural Patterns and Design Principles
- Modularity: The design leverages distinct modules (packages) for each concern: core functionality, framework-specific bindings, and external integrations.
- Dependency Injection: React bindings and Shopify components rely on a common core, which minimizes redundant code and encourages reusability.
- Separation of Concerns: Different directories, such as src, spec, tests, and configuration files, help delineate business logic from testing, configuration, and usage examples.
- Extensibility: Given the multiple “auto” components and hooks in the React package, the project is designed to be extensible for different application needs and integration scenarios.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Central Monorepo Node
    Monorepo["Monorepo"]:::monorepo
    MonorepoConfig["Monorepo Tooling & Configuration"]:::config

    %% Core Packages
    subgraph "Core Packages"
        ApiCore["API Client Core"]:::core
        ReactBindings["React Bindings"]:::react
        ReactShopify["React Shopify App Bridge"]:::shopify
        ShopifyExtensions["Shopify Extensions"]:::shopify
    end

    %% Sample & Utilities
    subgraph "Samples & Utilities"
        BlogExample["Blog Example (Sample App)"]:::sample
        TestBundles["Test Bundles"]:::sample
        TinyGraphQL["Tiny GraphQL Query Compiler"]:::sample
    end

    %% External Integration
    ShopifyEcosystem["Shopify Ecosystem"]:::external

    %% Relationships from Monorepo
    Monorepo --> MonorepoConfig
    Monorepo --> ApiCore
    Monorepo --> ReactBindings
    Monorepo --> ReactShopify
    Monorepo --> ShopifyExtensions
    Monorepo --> BlogExample
    Monorepo --> TestBundles
    Monorepo --> TinyGraphQL

    %% Configuration supports all packages
    MonorepoConfig --> ApiCore
    MonorepoConfig --> ReactBindings
    MonorepoConfig --> ReactShopify
    MonorepoConfig --> ShopifyExtensions
    MonorepoConfig --> BlogExample
    MonorepoConfig --> TestBundles
    MonorepoConfig --> TinyGraphQL

    %% Package Dependencies
    ReactBindings -->|"depends_on"| ApiCore
    ReactShopify -->|"depends_on"| ApiCore
    ShopifyExtensions -->|"depends_on"| ApiCore

    %% External Integration from React Shopify App Bridge
    ReactShopify -->|"integrates_with"| ShopifyEcosystem

    %% Click Events for Component Mapping
    click MonorepoConfig "https://github.com/gadget-inc/js-clients/blob/main/pnpm-lock.yaml"
    click ApiCore "https://github.com/gadget-inc/js-clients/tree/main/packages/api-client-core"
    click ReactBindings "https://github.com/gadget-inc/js-clients/tree/main/packages/react"
    click ReactShopify "https://github.com/gadget-inc/js-clients/tree/main/packages/react-shopify-app-bridge"
    click ShopifyExtensions "https://github.com/gadget-inc/js-clients/tree/main/packages/shopify-extensions"
    click BlogExample "https://github.com/gadget-inc/js-clients/tree/main/packages/blog-example"
    click TestBundles "https://github.com/gadget-inc/js-clients/tree/main/packages/test-bundles"
    click TinyGraphQL "https://github.com/gadget-inc/js-clients/tree/main/packages/tiny-graphql-query-compiler"

    %% Styles
    classDef monorepo fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef config fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef core fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef react fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef shopify fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef sample fill:#E6E6FA,stroke:#333,stroke-width:2px;
    classDef external fill:#FFA500,stroke:#333,stroke-width:2px;
```
