# bigcommerce/nextjs-commerce architecture

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

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

## Overview

1. **High-level shape**  
   This is a **Next.js App Router storefront** for **BigCommerce**. The app is mostly a server-rendered commerce frontend, with BigCommerce as the system of record for catalog, pages, search, and cart state.

2. **Route surface / user-facing entry points**  
   The main routes are:
   - `app/page.tsx` for the home page
   - `app/product/[handle]/page.tsx` for product detail pages
   - `app/search/page.tsx` and `app/search/[collection]/page.tsx` for browsing/searching collections
   - `app/[page]/page.tsx` for generic content pages
   - `app/api/revalidate/route.ts` for cache invalidation / revalidation
   There are also Next.js metadata routes for `robots.ts`, `sitemap.ts`, and Open Graph image generation.

3. **Rendering model**  
   The app uses **React Server Components** heavily via the App Router, with route-level `layout.tsx`, `loading.tsx`, and `error.tsx` boundaries. Shared chrome such as navigation and footer is composed in `app/layout.tsx` and segment layouts like `app/search/layout.tsx`.

4. **BigCommerce integration boundary**  
   All BigCommerce access is centralized under `lib/bigcommerce`. That layer contains:
   - GraphQL **queries** for cart, category, checkout, menu, page, product, and route resolution
   - **mutations** for cart updates
   - reusable **fragments**
   - **mappers** and **types** to convert BigCommerce GraphQL shapes into app-friendly models
   - storefront configuration/constants  
   This is the main boundary between the UI and the external commerce platform.

5. **Catalog and content data flow**  
   Product, category/collection, menu, and CMS page data are fetched through the `lib/bigcommerce` query layer and fed into route components under `app/`. The `app/[page]` route suggests generic page resolution, while `app/product/[handle]` and search routes map BigCommerce handles/collections to storefront pages.

6. **Search and browsing subsystem**  
   The search experience is split between route-level data fetching and UI filtering components:
   - `app/search/...` handles collection/search pages
   - `components/layout/search/*` contains filter, dropdown, and collections UI
   - `components/layout/product-grid-items.tsx` and `components/grid/*` render product listings  
   This is a distinct browsing subsystem centered on collection faceting and list rendering.

7. **Cart subsystem**  
   Cart logic is separated into:
   - `components/cart/*` for the drawer/modal and controls
   - `components/cart/actions.ts` for cart mutations/actions
   - BigCommerce cart queries/mutations in `lib/bigcommerce`  
   The cart is a client-interactive feature, but the authoritative state comes from BigCommerce via server-side API calls.

8. **Shared layout and navigation**  
   `components/layout/*` provides the storefront chrome:
   - navbar, mobile menu, and search entry points
   - footer and footer menu
   - shared search controls and product grid layout helpers  
   These components are reused across route segments to keep the storefront shell consistent.

9. **Presentation primitives**  
   The repo includes a set of reusable UI primitives in `components/` such as `carousel`, `price`, `label`, `loading-dots`, `prose`, icons, and product-specific elements like gallery and variant selector. Styling is handled with **Tailwind CSS** plus global styles in `app/globals.css`, with fonts managed in `fonts/`.

10. **SEO and social metadata**  
   The storefront is set up for indexability and share previews through:
   - `app/robots.ts`
   - `app/sitemap.ts`
   - route-specific and shared `opengraph-image.tsx` files
   - page/layout metadata in the App Router  
   This matters because the app is intended to be crawlable commerce content, not just an interactive SPA.

11. **Runtime and request-boundary concerns**  
   `middleware.ts` sits at the framework boundary for request-time handling, and `app/api/revalidate/route.ts` provides a controlled way to invalidate rendered content when upstream BigCommerce data changes. That suggests the storefront uses Next.js caching/revalidation rather than a separate backend.

12. **Tooling and deployment posture**  
   The repo is TypeScript-based and uses standard frontend tooling: ESLint, Prettier, Tailwind, PostCSS, and PNPM. The presence of `.env.example`, `.nvmrc`, and GitHub Actions indicates a Vercel-friendly deployment model with environment-driven BigCommerce credentials and CI test automation.

13. **Architectural summary**  
   The clearest diagram is: **browser → Next.js route/layout tree → BigCommerce GraphQL integration layer → BigCommerce storefront API**. Everything else in the repo is either presentation around that flow, or supporting infrastructure for search, cart, SEO, and cache invalidation.

Main entry points: [`lib/bigcommerce/queries/product.ts`](https://github.com/bigcommerce/nextjs-commerce/blob/main/lib/bigcommerce/queries/product.ts) (Storefront queries), [`app/layout.tsx`](https://github.com/bigcommerce/nextjs-commerce/blob/main/app/layout.tsx) (Root shell), [`components/layout/search/filter/index.tsx`](https://github.com/bigcommerce/nextjs-commerce/blob/main/components/layout/search/filter/index.tsx) (Browse UI), [`components/price.tsx`](https://github.com/bigcommerce/nextjs-commerce/blob/main/components/price.tsx) (Primitives)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Router"]
  node_app_layout["Root shell<br/>next layout<br/>[layout.tsx]"]
  node_app_home["Home page<br/>route<br/>[page.tsx]"]
  node_app_product["Product page<br/>route<br/>[page.tsx]"]
  node_app_search_root["Search page<br/>route<br/>[page.tsx]"]
  node_app_search_collection["Collection page<br/>route<br/>[page.tsx]"]
  node_app_content["Content page<br/>route<br/>[page.tsx]"]
  node_app_revalidate["Revalidate API<br/>api route<br/>[route.ts]"]
  node_app_seo["SEO routes<br/>metadata routes<br/>[robots.ts]"]
  node_search_layout["Search shell<br/>segment layout<br/>[layout.tsx]"]
end

subgraph group_components["UI Components"]
  node_search_ui["Browse UI<br/>search components<br/>[index.tsx]"]
  node_grid_ui["Product grid<br/>listing UI"]
  node_nav_shell["Site chrome<br/>layout components<br/>[index.tsx]"]
  node_cart_ui["Cart drawer<br/>cart UI<br/>[index.tsx]"]
  node_cart_actions["Cart actions<br/>client actions<br/>[actions.ts]"]
  node_product_ui["Product UI<br/>product components<br/>[gallery.tsx]"]
  node_primitives["Primitives<br/>shared UI<br/>[price.tsx]"]
end

subgraph group_bigcommerce["BigCommerce Layer"]
  node_bc_queries["Storefront queries<br/>graphql queries<br/>[product.ts]"]
  node_bc_mutations["Cart mutations<br/>graphql mutations<br/>[cart.ts]"]
  node_bc_data["Data models<br/>fragments and mappers<br/>[mappers.ts]"]
  node_bc_config["Storefront config<br/>commerce config<br/>[constants.ts]"]
end

subgraph group_infra["Infra"]
  node_middleware["Middleware<br/>request boundary<br/>[middleware.ts]"]
  node_styles["Styling<br/>build assets<br/>[globals.css]"]
end

node_app_layout -->|"composes"| node_nav_shell
node_app_layout -->|"mounts"| node_cart_ui
node_app_layout -->|"applies"| node_styles
node_app_home -->|"loads"| node_bc_queries
node_app_product -->|"loads"| node_bc_queries
node_app_product -->|"renders"| node_product_ui
node_app_search_root -->|"renders"| node_search_ui
node_app_search_collection -->|"renders"| node_search_ui
node_app_search_collection -->|"renders"| node_grid_ui
node_search_layout -->|"wraps"| node_search_ui
node_app_content -->|"loads"| node_bc_queries
node_app_seo -.->|"depends on"| node_bc_queries
node_app_revalidate -.->|"uses"| node_bc_config
node_cart_ui -->|"invokes"| node_cart_actions
node_cart_actions -->|"writes"| node_bc_mutations
node_bc_queries -->|"maps to"| node_bc_data
node_bc_mutations -.->|"shares models"| node_bc_data
node_bc_queries -.->|"configured by"| node_bc_config
node_middleware -.->|"guards"| node_app_layout
node_product_ui -->|"uses"| node_primitives
node_search_ui -->|"uses"| node_primitives
node_grid_ui -->|"uses"| node_primitives
node_nav_shell -->|"uses"| node_primitives

click node_app_layout "https://github.com/bigcommerce/nextjs-commerce/blob/main/app/layout.tsx"
click node_app_home "https://github.com/bigcommerce/nextjs-commerce/blob/main/app/page.tsx"
click node_app_product "https://github.com/bigcommerce/nextjs-commerce/blob/main/app/product/[handle]/page.tsx"
click node_app_search_root "https://github.com/bigcommerce/nextjs-commerce/blob/main/app/search/page.tsx"
click node_app_search_collection "https://github.com/bigcommerce/nextjs-commerce/blob/main/app/search/[collection]/page.tsx"
click node_app_content "https://github.com/bigcommerce/nextjs-commerce/blob/main/app/[page]/page.tsx"
click node_app_revalidate "https://github.com/bigcommerce/nextjs-commerce/blob/main/app/api/revalidate/route.ts"
click node_app_seo "https://github.com/bigcommerce/nextjs-commerce/blob/main/app/robots.ts"
click node_search_layout "https://github.com/bigcommerce/nextjs-commerce/blob/main/app/search/layout.tsx"
click node_search_ui "https://github.com/bigcommerce/nextjs-commerce/blob/main/components/layout/search/filter/index.tsx"
click node_grid_ui "https://github.com/bigcommerce/nextjs-commerce/blob/main/components/layout/product-grid-items.tsx"
click node_nav_shell "https://github.com/bigcommerce/nextjs-commerce/blob/main/components/layout/navbar/index.tsx"
click node_cart_ui "https://github.com/bigcommerce/nextjs-commerce/blob/main/components/cart/index.tsx"
click node_cart_actions "https://github.com/bigcommerce/nextjs-commerce/blob/main/components/cart/actions.ts"
click node_product_ui "https://github.com/bigcommerce/nextjs-commerce/blob/main/components/product/gallery.tsx"
click node_primitives "https://github.com/bigcommerce/nextjs-commerce/blob/main/components/price.tsx"
click node_bc_queries "https://github.com/bigcommerce/nextjs-commerce/blob/main/lib/bigcommerce/queries/product.ts"
click node_bc_mutations "https://github.com/bigcommerce/nextjs-commerce/blob/main/lib/bigcommerce/mutations/cart.ts"
click node_bc_data "https://github.com/bigcommerce/nextjs-commerce/blob/main/lib/bigcommerce/mappers.ts"
click node_bc_config "https://github.com/bigcommerce/nextjs-commerce/blob/main/lib/bigcommerce/constants.ts"
click node_middleware "https://github.com/bigcommerce/nextjs-commerce/blob/main/middleware.ts"
click node_styles "https://github.com/bigcommerce/nextjs-commerce/blob/main/app/globals.css"

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_product,node_app_search_root,node_app_search_collection,node_app_content,node_app_revalidate,node_app_seo,node_search_layout toneBlue
class node_search_ui,node_grid_ui,node_nav_shell,node_cart_ui,node_cart_actions,node_product_ui,node_primitives toneAmber
class node_bc_queries,node_bc_mutations,node_bc_data,node_bc_config toneMint
class node_middleware,node_styles toneRose
```

## Components

### App Router

Next.js routes, layouts, metadata, and API boundaries.

- [Root shell](https://github.com/bigcommerce/nextjs-commerce/blob/main/app/layout.tsx): next layout · Global App Router shell with shared providers and chrome. · `app/layout.tsx`
- [Home page](https://github.com/bigcommerce/nextjs-commerce/blob/main/app/page.tsx): route · Storefront landing page. · `app/page.tsx`
- [Product page](https://github.com/bigcommerce/nextjs-commerce/blob/main/app/product/[handle]/page.tsx): route · Product detail route by handle. · `app/product/[handle]/page.tsx`
- [Search page](https://github.com/bigcommerce/nextjs-commerce/blob/main/app/search/page.tsx): route · Entry point for browsing and search. · `app/search/page.tsx`
- [Collection page](https://github.com/bigcommerce/nextjs-commerce/blob/main/app/search/[collection]/page.tsx): route · Collection-specific search and browse route. · `app/search/[collection]/page.tsx`
- [Content page](https://github.com/bigcommerce/nextjs-commerce/blob/main/app/[page]/page.tsx): route · Generic CMS/page resolution route. · `app/[page]/page.tsx`
- [Revalidate API](https://github.com/bigcommerce/nextjs-commerce/blob/main/app/api/revalidate/route.ts): api route · Cache invalidation endpoint for upstream content changes. · `app/api/revalidate/route.ts`
- [SEO routes](https://github.com/bigcommerce/nextjs-commerce/blob/main/app/robots.ts): metadata routes · Robots, sitemap, and Open Graph image generation. · `app/robots.ts`
- [Search shell](https://github.com/bigcommerce/nextjs-commerce/blob/main/app/search/layout.tsx): segment layout · Search segment layout and loading boundary. · `app/search/layout.tsx`

### UI Components

Reusable storefront chrome, product, cart, and browsing UI.

- [Browse UI](https://github.com/bigcommerce/nextjs-commerce/blob/main/components/layout/search/filter/index.tsx): search components · Filter, dropdown, and collection browsing controls. · `components/layout/search/filter/index.tsx`
- [Product grid](https://github.com/bigcommerce/nextjs-commerce/blob/main/components/layout/product-grid-items.tsx): listing UI · Shared product list rendering for search and category views. · `components/layout/product-grid-items.tsx`
- [Site chrome](https://github.com/bigcommerce/nextjs-commerce/blob/main/components/layout/navbar/index.tsx): layout components · Navbar, mobile menu, footer, and footer menu. · `components/layout/navbar/index.tsx`
- [Cart drawer](https://github.com/bigcommerce/nextjs-commerce/blob/main/components/cart/index.tsx): cart UI · Interactive cart modal and item controls. · `components/cart/index.tsx`
- [Cart actions](https://github.com/bigcommerce/nextjs-commerce/blob/main/components/cart/actions.ts): client actions · Add, edit, delete, open, and close cart interactions. · `components/cart/actions.ts`
- [Product UI](https://github.com/bigcommerce/nextjs-commerce/blob/main/components/product/gallery.tsx): product components · Gallery, description, and variant selection widgets. · `components/product/gallery.tsx`
- [Primitives](https://github.com/bigcommerce/nextjs-commerce/blob/main/components/price.tsx): shared UI · Reusable display pieces such as price, labels, prose, icons, and carousel. · `components/price.tsx`

### BigCommerce Layer

Queries, mutations, fragments, and mapping around the storefront API.

- [Storefront queries](https://github.com/bigcommerce/nextjs-commerce/blob/main/lib/bigcommerce/queries/product.ts): graphql queries · BigCommerce GraphQL access for product, category, menu, page, checkout, and route resolution. · `lib/bigcommerce/queries/product.ts`
- [Cart mutations](https://github.com/bigcommerce/nextjs-commerce/blob/main/lib/bigcommerce/mutations/cart.ts): graphql mutations · BigCommerce cart update operations. · `lib/bigcommerce/mutations/cart.ts`
- [Data models](https://github.com/bigcommerce/nextjs-commerce/blob/main/lib/bigcommerce/mappers.ts): fragments and mappers · Fragments, types, and mapping from BigCommerce shapes to app models. · `lib/bigcommerce/mappers.ts`
- [Storefront config](https://github.com/bigcommerce/nextjs-commerce/blob/main/lib/bigcommerce/constants.ts): commerce config · Constants and storefront configuration for the BigCommerce integration. · `lib/bigcommerce/constants.ts`

### Infra

Runtime, styling, and build/config support.

- [Middleware](https://github.com/bigcommerce/nextjs-commerce/blob/main/middleware.ts): request boundary · Framework-level request interception and routing concerns. · `middleware.ts`
- [Styling](https://github.com/bigcommerce/nextjs-commerce/blob/main/app/globals.css): build assets · Global CSS and Tailwind-based presentation layer. · `app/globals.css`

## Connections

- Root shell → Site chrome: composes · Root shell composes shared site chrome.
- Root shell → Cart drawer: mounts · Cart drawer is available from the global shell.
- Root shell → Styling: applies · Global styles support the App Router shell.
- Home page → Storefront queries: loads · Home page fetches catalog and storefront data.
- Product page → Storefront queries: loads · Product route resolves product data from BigCommerce.
- Product page → Product UI: renders · Product page uses gallery and variant controls.
- Search page → Browse UI: renders · Search entry page uses browse and filter controls.
- Collection page → Browse UI: renders · Collection route uses faceting and dropdown filters.
- Collection page → Product grid: renders · Collection results are shown in product grids.
- Search shell → Browse UI: wraps · Search segment layout organizes the browsing experience.
- Content page → Storefront queries: loads · Generic pages are resolved through BigCommerce content queries.
- SEO routes → Storefront queries: depends on · SEO metadata and routes derive from storefront content.
- Revalidate API → Storefront config: uses · Revalidation endpoint follows storefront configuration.
- Cart drawer → Cart actions: invokes · Cart controls trigger client actions and mutations.
- Cart actions → Cart mutations: writes · Cart updates are persisted through BigCommerce mutations.
- Storefront queries → Data models: maps to · Query results are normalized into app-friendly models.
- Cart mutations → Data models: shares models · Mutations reuse the same cart/product data shapes.
- Storefront queries → Storefront config: configured by · Queries rely on storefront constants and API setup.
- Middleware → Root shell: guards · Request-time handling sits in front of the app routes.
- Product UI → Primitives: uses · Product widgets are built from shared presentation primitives.
- Browse UI → Primitives: uses · Search controls share common UI pieces and icons.
- Product grid → Primitives: uses · Listing tiles reuse core visual primitives.
- Site chrome → Primitives: uses · Navbar and footer use shared branding and icon primitives.
