# vercel/commerce architecture

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

- Interactive diagram: https://gitdiagram.com/vercel/commerce
- Repository: https://github.com/vercel/commerce

## Overview

1. **Overall architecture**
   - This is a **Next.js App Router** ecommerce storefront, built around **server-rendered React Server Components** with selective client-side islands for interactivity.
   - The repo is structured as a thin presentation layer on top of a Shopify-specific data adapter in `lib/shopify`.

2. **Routing surface**
   - The `app/` directory defines the public site routes: home (`app/page.tsx`), generic CMS pages (`app/[page]`), product detail pages (`app/product/[handle]`), and search/browse pages (`app/search/...`).
   - `app/layout.tsx` and nested layout files provide the shared shell, navigation, footer, search UI, and per-section wrappers.

3. **Shopify integration boundary**
   - `lib/shopify/` is the main backend boundary for the whole app.
   - It contains **GraphQL fragments, queries, and mutations** for Shopify resources such as products, collections, menus, pages, carts, images, and SEO data.
   - The rest of the app is intentionally provider-agnostic in shape; swapping commerce providers would mostly mean replacing this folder.

4. **Data flow for storefront pages**
   - Page routes fetch data on the server through `lib/shopify` and compose it into UI components under `components/`.
   - Product and collection browsing is driven by Shopify catalog data, while page content and menus come from CMS-like Shopify resources.
   - SEO metadata and social images are derived from the same fetched records where possible.

5. **Product detail subsystem**
   - `app/product/[handle]/page.tsx` renders individual product pages.
   - Supporting components in `components/product/` handle the product gallery, description, and variant selection.
   - This is where product-specific state such as selected variant and displayed images is localized.

6. **Search and collection browsing**
   - `app/search/page.tsx` and `app/search/[collection]/page.tsx` support catalog discovery.
   - The search area has its own layout and loading state, plus helper components for collections and filtering under `components/layout/search/`.
   - This portion of the app is the main browse/filter entry point rather than a separate search backend.

7. **Cart subsystem**
   - Cart behavior is isolated in `components/cart/` and backed by Shopify cart queries/mutations in `lib/shopify`.
   - The cart uses **client-side state/context** for UI updates, while the actual create/update/delete operations are handled through server-backed actions and mutations.
   - UI pieces include add-to-cart controls, quantity editing, deletion, an open-cart trigger, and a cart modal.

8. **Mutation and refresh path**
   - `app/api/revalidate/route.ts` is the explicit server endpoint for cache invalidation.
   - This is intended for Shopify-triggered updates, so the storefront can revalidate content after catalog or content changes rather than waiting for TTL expiry.
   - That makes the app behave like a cached SSR storefront with webhook-driven freshness.

9. **SEO, metadata, and sharing**
   - The app includes route-level metadata support via `opengraph-image.tsx`, `robots.ts`, and `sitemap.ts`.
   - Dynamic OG images exist for the root, generic pages, products, and search collections, so shared links have route-specific previews.
   - SEO fields are also part of the Shopify query layer, not just hardcoded metadata.

10. **Shared UI and layout system**
   - `components/layout/` contains the site chrome: navbar, mobile menu, search entry, footer, and product grid scaffolding.
   - `components/grid/`, `components/carousel.tsx`, `components/price.tsx`, `components/prose.tsx`, and similar files are reusable presentation primitives.
   - These components are mostly stateless and used to assemble the page-specific routes.

11. **Cross-cutting client components**
   - A few components are explicitly client-side for interactivity, such as welcome toast, cart controls, dropdown filters, and modal UI.
   - Most other rendering remains server-side, which keeps page composition fast and minimizes client bundle size.

12. **Runtime, config, and deployment assumptions**
   - The project is designed for **Vercel deployment** and depends on environment variables for Shopify domain, storefront token, revalidation secret, company name, and site name.
   - `next.config.ts`, `postcss.config.mjs`, `tsconfig.json`, and the font/CSS setup define the framework and styling boundaries, but they do not introduce additional backend services.

Main entry points: [`lib/shopify/index.ts`](https://github.com/vercel/commerce/blob/main/lib/shopify/index.ts) (Shopify entry), [`app/layout.tsx`](https://github.com/vercel/commerce/blob/main/app/layout.tsx) (Root layout), [`components/layout/search/collections.tsx`](https://github.com/vercel/commerce/blob/main/components/layout/search/collections.tsx) (Search UI), [`lib/shopify/queries/product.ts`](https://github.com/vercel/commerce/blob/main/lib/shopify/queries/product.ts) (Queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App routes"]
  node_app_layout["Root layout<br/>next layout<br/>[layout.tsx]"]
  node_app_home["Home page<br/>route<br/>[page.tsx]"]
  node_app_cms_page["CMS page<br/>route<br/>[page.tsx]"]
  node_app_product_page["Product page<br/>route<br/>[page.tsx]"]
  node_app_search_page["Search page<br/>route<br/>[page.tsx]"]
  node_app_search_collection["Collection page<br/>route<br/>[page.tsx]"]
  node_app_search_layout["Search layout<br/>[layout.tsx]"]
  node_app_revalidate["Revalidate API<br/>route handler<br/>[route.ts]"]
  node_app_metadata["SEO assets<br/>metadata"]
end

subgraph group_components["UI system"]
  node_ui_navbar["Navbar<br/>layout chrome<br/>[index.tsx]"]
  node_ui_footer["Footer<br/>layout chrome<br/>[footer.tsx]"]
  node_ui_search["Search UI<br/>browse widgets<br/>[collections.tsx]"]
  node_ui_product["Product UI<br/>product widgets<br/>[gallery.tsx]"]
  node_ui_cart["Cart UI<br/>client cart<br/>[cart-context.tsx]"]
  node_ui_grid["Grid tiles<br/>presentation<br/>[index.tsx]"]
  node_ui_primitives["Primitives<br/>ui helpers<br/>[price.tsx]"]
end

subgraph group_shopify["Shopify adapter"]
  node_shopify_index["Shopify entry<br/>adapter entry<br/>[index.ts]"]
  node_shopify_queries["Queries<br/>[product.ts]"]
  node_shopify_mutations["Mutations<br/>[cart.ts]"]
  node_shopify_fragments["Fragments<br/>[product.ts]"]
end

subgraph group_lib["Shared libs"]
  node_lib_utils["Shared utils<br/>helpers<br/>[constants.ts]"]
end

node_app_layout -->|"renders"| node_ui_navbar
node_app_layout -->|"renders"| node_ui_footer
node_app_layout -->|"uses"| node_ui_primitives
node_app_home -->|"fetches"| node_shopify_index
node_app_home -->|"renders"| node_ui_grid
node_app_cms_page -->|"fetches"| node_shopify_index
node_app_cms_page -->|"renders"| node_ui_primitives
node_app_product_page -->|"fetches"| node_shopify_index
node_app_product_page -->|"renders"| node_ui_product
node_app_search_layout -->|"wraps"| node_ui_search
node_app_search_page -->|"fetches"| node_shopify_index
node_app_search_page -->|"renders"| node_ui_search
node_app_search_collection -->|"fetches"| node_shopify_index
node_app_revalidate -->|"invalidates"| node_shopify_index
node_app_metadata -->|"derives from"| node_shopify_index
node_ui_navbar -->|"links to"| node_ui_search
node_ui_cart -->|"writes"| node_shopify_mutations
node_ui_cart -->|"reads"| node_shopify_queries
node_ui_product -->|"shapes with"| node_shopify_fragments
node_ui_search -->|"filters"| node_shopify_queries
node_shopify_index -->|"re-exports"| node_shopify_queries
node_shopify_index -->|"re-exports"| node_shopify_mutations
node_shopify_index -->|"re-exports"| node_shopify_fragments
node_shopify_queries -->|"uses"| node_shopify_fragments
node_shopify_mutations -->|"uses"| node_shopify_fragments
node_app_layout -->|"uses"| node_lib_utils

click node_app_layout "https://github.com/vercel/commerce/blob/main/app/layout.tsx"
click node_app_home "https://github.com/vercel/commerce/blob/main/app/page.tsx"
click node_app_cms_page "https://github.com/vercel/commerce/blob/main/app/[page]/page.tsx"
click node_app_product_page "https://github.com/vercel/commerce/blob/main/app/product/[handle]/page.tsx"
click node_app_search_page "https://github.com/vercel/commerce/blob/main/app/search/page.tsx"
click node_app_search_collection "https://github.com/vercel/commerce/blob/main/app/search/[collection]/page.tsx"
click node_app_search_layout "https://github.com/vercel/commerce/blob/main/app/search/layout.tsx"
click node_app_revalidate "https://github.com/vercel/commerce/blob/main/app/api/revalidate/route.ts"
click node_ui_navbar "https://github.com/vercel/commerce/blob/main/components/layout/navbar/index.tsx"
click node_ui_footer "https://github.com/vercel/commerce/blob/main/components/layout/footer.tsx"
click node_ui_search "https://github.com/vercel/commerce/blob/main/components/layout/search/collections.tsx"
click node_ui_product "https://github.com/vercel/commerce/blob/main/components/product/gallery.tsx"
click node_ui_cart "https://github.com/vercel/commerce/blob/main/components/cart/cart-context.tsx"
click node_ui_grid "https://github.com/vercel/commerce/blob/main/components/grid/index.tsx"
click node_ui_primitives "https://github.com/vercel/commerce/blob/main/components/price.tsx"
click node_shopify_index "https://github.com/vercel/commerce/blob/main/lib/shopify/index.ts"
click node_shopify_queries "https://github.com/vercel/commerce/blob/main/lib/shopify/queries/product.ts"
click node_shopify_mutations "https://github.com/vercel/commerce/blob/main/lib/shopify/mutations/cart.ts"
click node_shopify_fragments "https://github.com/vercel/commerce/blob/main/lib/shopify/fragments/product.ts"
click node_lib_utils "https://github.com/vercel/commerce/blob/main/lib/constants.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_layout,node_app_home,node_app_cms_page,node_app_product_page,node_app_search_page,node_app_search_collection,node_app_search_layout,node_app_revalidate,node_app_metadata toneBlue
class node_ui_navbar,node_ui_footer,node_ui_search,node_ui_product,node_ui_cart,node_ui_grid,node_ui_primitives toneAmber
class node_shopify_index,node_shopify_queries,node_shopify_mutations,node_shopify_fragments toneMint
class node_lib_utils toneRose
```

## Components

### App routes

Next.js App Router pages, layouts, metadata, and API endpoints.

- [Root layout](https://github.com/vercel/commerce/blob/main/app/layout.tsx): next layout · Global shell, providers, fonts, and shared chrome. · `app/layout.tsx`
- [Home page](https://github.com/vercel/commerce/blob/main/app/page.tsx): route · Storefront landing page. · `app/page.tsx`
- [CMS page](https://github.com/vercel/commerce/blob/main/app/[page]/page.tsx): route · Generic content page route for Shopify-backed pages. · `app/[page]/page.tsx`
- [Product page](https://github.com/vercel/commerce/blob/main/app/product/[handle]/page.tsx): route · Individual product detail route. · `app/product/[handle]/page.tsx`
- [Search page](https://github.com/vercel/commerce/blob/main/app/search/page.tsx): route · Catalog discovery and browse entry point. · `app/search/page.tsx`
- [Collection page](https://github.com/vercel/commerce/blob/main/app/search/[collection]/page.tsx): route · Search/browse route scoped to a collection. · `app/search/[collection]/page.tsx`
- [Search layout](https://github.com/vercel/commerce/blob/main/app/search/layout.tsx): layout · Shared search section shell and wrappers. · `app/search/layout.tsx`
- [Revalidate API](https://github.com/vercel/commerce/blob/main/app/api/revalidate/route.ts): route handler · Webhook-friendly cache invalidation endpoint. · `app/api/revalidate/route.ts`
- **SEO assets**: metadata · Robots, sitemap, and route-specific Open Graph images.

### UI system

Shared presentation components and client-side islands.

- [Navbar](https://github.com/vercel/commerce/blob/main/components/layout/navbar/index.tsx): layout chrome · Primary navigation, search entry, and mobile menu. · `components/layout/navbar/index.tsx`
- [Footer](https://github.com/vercel/commerce/blob/main/components/layout/footer.tsx): layout chrome · Footer menus and site footer. · `components/layout/footer.tsx`
- [Search UI](https://github.com/vercel/commerce/blob/main/components/layout/search/collections.tsx): browse widgets · Collection list and filter controls for search/browse. · `components/layout/search/collections.tsx`
- [Product UI](https://github.com/vercel/commerce/blob/main/components/product/gallery.tsx): product widgets · Gallery, description, and variant selection. · `components/product/gallery.tsx`
- [Cart UI](https://github.com/vercel/commerce/blob/main/components/cart/cart-context.tsx): client cart · Cart context, modal, and item actions. · `components/cart/cart-context.tsx`
- [Grid tiles](https://github.com/vercel/commerce/blob/main/components/grid/index.tsx): presentation · Reusable product and content grid presentation. · `components/grid/index.tsx`
- [Primitives](https://github.com/vercel/commerce/blob/main/components/price.tsx): ui helpers · Shared rendering helpers like price, prose, carousel, and labels. · `components/price.tsx`

### Shopify adapter

Queries, mutations, fragments, and typed boundary for commerce data.

- [Shopify entry](https://github.com/vercel/commerce/blob/main/lib/shopify/index.ts): adapter entry · Central Shopify API surface used by routes. · `lib/shopify/index.ts`
- [Queries](https://github.com/vercel/commerce/blob/main/lib/shopify/queries/product.ts): graphql queries · Catalog, page, menu, and cart read operations. · `lib/shopify/queries/product.ts`
- [Mutations](https://github.com/vercel/commerce/blob/main/lib/shopify/mutations/cart.ts): graphql mutations · Cart and write operations against Shopify. · `lib/shopify/mutations/cart.ts`
- [Fragments](https://github.com/vercel/commerce/blob/main/lib/shopify/fragments/product.ts): graphql fragments · Shared GraphQL fragments for cart, product, image, and SEO data. · `lib/shopify/fragments/product.ts`

### Shared libs

Non-Shopify utilities and constants used across the app.

- [Shared utils](https://github.com/vercel/commerce/blob/main/lib/constants.ts): helpers · Constants, utility functions, and type guards. · `lib/constants.ts`

## Connections

- Root layout → Navbar: renders · Root shell composes global navigation.
- Root layout → Footer: renders · Root shell composes site footer.
- Root layout → Primitives: uses · Shared presentation helpers appear across the shell.
- Home page → Shopify entry: fetches · Home page loads storefront data server-side.
- Home page → Grid tiles: renders · Home page composes product/content tiles.
- CMS page → Shopify entry: fetches · Generic page route reads CMS-like Shopify content.
- CMS page → Primitives: renders · Content pages use prose and media primitives.
- Product page → Shopify entry: fetches · Product detail page loads product and SEO data.
- Product page → Product UI: renders · Product detail page composes gallery and variant UI.
- Search layout → Search UI: wraps · Search section layout provides browse/filter chrome.
- Search page → Shopify entry: fetches · Search page reads catalog and collection data.
- Search page → Search UI: renders · Search page renders browse and filter controls.
- Collection page → Shopify entry: fetches · Collection-scoped search page loads collection data.
- Revalidate API → Shopify entry: invalidates · Webhook-triggered refresh aligns storefront cache with Shopify updates.
- SEO assets → Shopify entry: derives from · Robots, sitemap, and OG images are driven by store data.
- Navbar → Search UI: links to · Navigation includes search entry and related browse UI.
- Cart UI → Mutations: writes · Cart UI triggers create/update/delete cart mutations.
- Cart UI → Queries: reads · Cart state is hydrated from Shopify cart reads.
- Product UI → Fragments: shapes with · Product UI depends on catalog fields and image fragments.
- Search UI → Queries: filters · Browse controls operate on catalog query results.
- Shopify entry → Queries: re-exports · Central adapter exposes read operations to routes.
- Shopify entry → Mutations: re-exports · Central adapter exposes write operations to routes.
- Shopify entry → Fragments: re-exports · Central adapter shares common GraphQL fragments.
- Queries → Fragments: uses · Queries compose shared fragments for consistency.
- Mutations → Fragments: uses · Mutations reuse fragments for cart payloads.
- Root layout → Shared utils: uses · Global shell relies on shared constants and utilities.
