# shopify/hydrogen architecture

> Architecture diagram of the GitHub repository shopify/hydrogen, 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/shopify/hydrogen
- Repository: https://github.com/shopify/hydrogen

## Overview

##### Project’s Core Purpose and Type
- The project is a monorepo focused on the Hydrogen stack from Shopify—specialized for headless commerce. Its primary purpose is to provide a complete toolkit including UI components, CLI tools, code generators, server adapters, and development environments (both production Oxygen runtime and local simulation with mini-oxygen) for building commerce applications.
- It integrates tightly with Remix (a full stack web framework) and is architected so that each package plays a specific role in the overall ecosystem.

##### Main Components
- Core Framework (“@shopify/hydrogen”): This package provides opinionated tools, utilities, and examples to build dynamic commerce applications.
- React Component Library (“@shopify/hydrogen-react”): Exposes a rich set of Shopify-specific commerce UI components, hooks, and utilities that can be used with any React-based framework.
- CLI Tools (“@shopify/cli-hydrogen”): Command-line interface commands and utilities for creating projects, development, deployment, and linking to Shopify storefronts.
- Project Generator (“@shopify/create-hydrogen”): Scaffold a new Hydrogen project from the command line.
- Code Generation (“@shopify/hydrogen-codegen”): Automates type generation for Storefront API GraphQL operations.
- Remix Adapter (“@shopify/remix-oxygen”): Enables Hydrogen apps to run on Shopify’s Oxygen runtime by integrating with Remix.
- Local Runtime Simulation (“@shopify/mini-oxygen”): Provides a local simulation of the Oxygen production environment.
- Ancillary Documentation, Cookbook, Templates, and Examples: These folders and packages (like “cookbook”, “docs”, “examples”, “templates”) illustrate usage patterns and provide guidelines.

##### Out Component Relationships and Interactions
- At the core is the Hydrogen framework that encapsulates domain-specific logic and commerce utilities. It interacts with:
- The Hydrogen React library, which provides prebuilt UI components and hooks that render on the client.
- The CLI tool and create-hydrogen package that help developers scaffold and manage their projects.
- The code generation package that runs during development/build to ensure type accuracy with backend (Storefront API) GraphQL queries.
- The Remix integration (via remix-oxygen) and mini-oxygen are responsible for bridging between the app’s server/environment runtime and the production hosting (Oxygen).
- The examples and templates are used by developers as sample implementations and starting points, demonstrating best practices and integration patterns.
- Data flows include API calls to Shopify (through GraphQL endpoints), which are abstracted by both the core Hydrogen libraries and by the React components. The CLI also facilitates tasks like building, deploying, and code generation, interacting with the local environment and remote deployments.

##### Architectural Patterns and Design Principles
- Monorepo Organization: The clearly separated packages in the “packages” directory denote strict modularity based on single responsibilities (UI, CLI, scaffolding, codegen, runtime adapters).
- Layered Architecture: The design naturally separates presentation (Hydrogen React), application logic (Hydrogen core), and tooling/infrastructure (CLI, codegen, remix-oxygen, mini-oxygen).
- Integration with External Services: The system interacts with Shopify’s Storefront API via GraphQL and leverages Remix for full-stack web rendering.
- Reusability and Extensibility: The availability of a “cookbook” and “templates” folder suggests an emphasis on extensibility and providing developers with plug-and-play components.

##### Final Inclusions
- Each component (e.g., Hydrogen Core, Hydrogen React, CLI, etc.) should be clearly labeled.
- Optionally, include annotations for critical configuration files (like the GraphQL configuration, tsconfig files, and workflows under .github) to indicate integration with CI/CD and testing setups.
- Don’t forget to include the “Examples” and “Templates” which serve as actual implementations that demonstrate how the various architectural pieces come together.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Packages"
        HC["Hydrogen Core"]
        HR["Hydrogen React"]
        CH["Hydrogen Codegen"]
        CT(("CLI Tools"))
        CG(("Project Generator"))
        RA{{"Remix Adapter"}}
        LO{{"Local Runtime Simulation"}}
    end

    subgraph "Developer Resources"
        EX["Examples"]
        TP["Templates"]
        DOC["Documentation"]
        CK["Cookbook"]
    end

    %% Package Relationships
    CT -->|"scaffold"| CG
    CT -->|"orchestrates"| HC
    CG -->|"initiates"| HC
    CH -->|"generatesTypes"| HC
    HC -->|"supportsUI"| HR
    HR -->|"integratesWith"| RA
    HR -->|"integratesWith"| LO

    %% Developer Resources Interactions
    HC -->|"referencedBy"| EX
    HC -->|"referencedBy"| DOC
    HR -->|"referencedBy"| CK
    TP -->|"providesStarter"| CG

    %% Styles
    classDef library fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef tool fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef runtime fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef resource fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;

    class HC,HR,CH library;
    class CT,CG tool;
    class RA,LO runtime;
    class EX,TP,DOC,CK resource;

    %% Click Events
    click HC "https://github.com/shopify/hydrogen/tree/main/packages/hydrogen"
    click HR "https://github.com/shopify/hydrogen/tree/main/packages/hydrogen-react"
    click CH "https://github.com/shopify/hydrogen/tree/main/packages/hydrogen-codegen"
    click CT "https://github.com/shopify/hydrogen/tree/main/packages/cli"
    click CG "https://github.com/shopify/hydrogen/tree/main/packages/create-hydrogen"
    click RA "https://github.com/shopify/hydrogen/tree/main/packages/remix-oxygen"
    click LO "https://github.com/shopify/hydrogen/tree/main/packages/mini-oxygen"
    click EX "https://github.com/shopify/hydrogen/tree/main/examples"
    click TP "https://github.com/shopify/hydrogen/tree/main/templates/skeleton"
    click DOC "https://github.com/shopify/hydrogen/tree/main/docs"
    click CK "https://github.com/shopify/hydrogen/tree/main/cookbook"
```
