# kirill-zhirnov/boundless-nextjs-ecommerce-template architecture

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

- Interactive diagram: https://gitdiagram.com/kirill-zhirnov/boundless-nextjs-ecommerce-template
- Repository: https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template

## Overview

1. This repository is a Next.js + TypeScript storefront template for Boundless Commerce. Architecturally it is a mostly server-rendered/catalog-driven e-commerce front end that consumes Boundless’s headless commerce API and delegates checkout to a separate Boundless checkout flow.

2. The app is organized around Next.js page routes in `pages/`. Key entry points are the home page, category listing (`/category/[slug]`), product detail (`/product/[slug]`), cart, checkout catch-all route, thank-you page, a CMS-style page route (`/page/cover`), and a generated `sitemap.xml`. These routes define the top-level navigation and the main SEO-visible content surfaces.

3. Shared page framing lives in `layouts/Main.tsx` and the reusable shell components in `components/` such as `Header`, `Footer`, menus, breadcrumbs, and the loading/alert widgets. The layout layer is responsible for composing the common store chrome around every page and for keeping the catalog/cart UI consistent.

4. Data access and domain transformation are concentrated in `lib/`. This folder likely acts as the boundary between Boundless API responses and UI-friendly models: `api.ts` for API calls, `product.ts`, `category.ts`, `menu.ts`, `breadcrumbs.ts`, `meta.ts`, `urls.ts`, `imgs.ts`, and `calculator.ts` for shaping content, links, image URLs, and pricing/derived values. These helpers are the main place where external API data becomes presentation-ready.

5. State management is centralized in Redux under `redux/`. The store has separate slices for cart, alerts, aside menu state, app state, and XHR/loading state, plus cart actions. This indicates a global-state boundary for interactive cross-page concerns such as cart contents, mobile menu open/close state, user alerts, and request lifecycle flags.

6. The cart subsystem is a first-class feature rather than a simple form. Components under `components/cart/` handle cart rows, loaders, and the header cart widget; the Redux cart slice keeps the canonical cart state; and the checkout page route bridges from the storefront cart into the external checkout experience. This creates a clear separation between browsing and purchase completion.

7. Catalog browsing is split into reusable subcomponents for categories, filters, sorting, pagination, and product cards. `components/category/`, `components/filterForm/`, `components/ProductsList.tsx`, and `components/ProductsSlider*.tsx` together form the browsing pipeline: category pages load products, pass them through filters/sort controls, and render them in list or carousel form. This is the main merchandising/data-discovery path in the app.

8. Product detail pages are built from a dedicated product component family under `components/product/`. The page combines gallery/images, labels, characteristics, variant selection, pricing, shipping info, and schema/metadata generation. This area is the boundary where product identity, variant selection, and purchase intent are resolved before an item reaches the cart.

9. SEO and metadata are deliberately built into the architecture. The presence of `MetaSchemaOrg`, sitemap generation, breadcrumbs, and URL/meta helper modules shows that pages are expected to produce crawlable, structured output. The `BOUNDLESS_BASE_URL` environment option is specifically used to emit absolute URLs for sitemap and social metadata.

10. Styling is handled with SCSS, not CSS-in-JS. Global variables, mixins, functions, component-specific styles, and a sample theme live under `styles/`, with a `themes/sample` override structure suggesting the template is designed for branding/customization without changing component logic. UI structure and visual theme are therefore decoupled.

11. The app is wired for responsive storefront behavior and mobile interactions: aside menu/backdrop, horizontal/vertical menus, filters modal, sliders, loaders, and dedicated mobile-oriented components. The inclusion of Swiper-based slider components and nprogress/loader styles indicates asynchronous page transitions and marketing-style content carousels are part of the intended user experience.

12. Runtime integration is defined by environment variables in `.env.example`: a permanent API token, instance ID, and optional base URL/image proportion. In architectural terms, the storefront depends on the Boundless Commerce service for catalog, content, and checkout data, while static assets and public web manifest/robots files support deployment as a conventional Next.js site.

Main entry points: [`layouts/Main.tsx`](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/layouts/Main.tsx) (Main layout), [`lib/api.ts`](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/lib/api.ts) (API client), [`components/product/PriceAndBuy.tsx`](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/components/product/PriceAndBuy.tsx) (Product UI), [`components/ProductsList.tsx`](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/components/ProductsList.tsx) (Catalog UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pages["Pages"]
  node_pages_index["Home<br/>route<br/>[index.tsx]"]
  node_pages_category["Category<br/>route<br/>[[slug].tsx]"]
  node_pages_product["Product<br/>route<br/>[[slug].tsx]"]
  node_pages_cart["Cart<br/>route<br/>[cart.tsx]"]
  node_pages_checkout["Checkout<br/>route<br/>[[[...slug]].tsx]"]
  node_pages_thankyou["Thank you<br/>route<br/>[[id].tsx]"]
  node_pages_cover["CMS page<br/>route<br/>[cover.tsx]"]
  node_pages_sitemap["Sitemap<br/>seo route<br/>[sitemap.xml.ts]"]
end

subgraph group_components["Components"]
  node_layout_main["Main layout<br/>shell<br/>[Main.tsx]"]
  node_components_header["Header<br/>chrome<br/>[Header.tsx]"]
  node_components_footer["Footer<br/>chrome<br/>[Footer.tsx]"]
  node_components_catalog["Catalog UI<br/>browse ui<br/>[ProductsList.tsx]"]
  node_components_product["Product UI<br/>[PriceAndBuy.tsx]"]
  node_components_cart["Cart UI<br/>[CartItems.tsx]"]
  node_components_navigation["Menus<br/>navigation<br/>[HorizontalMenu.tsx]"]
end

subgraph group_lib["Domain lib"]
  node_lib_api["API client<br/>boundary<br/>[api.ts]"]
  node_lib_domain["Domain mappers<br/>transform<br/>[product.ts]"]
  node_lib_pricing["Pricing<br/>calculation<br/>[calculator.ts]"]
end

subgraph group_state["Redux state"]
  node_redux_store["Store<br/>state container<br/>[store.ts]"]
  node_redux_slices["Slices<br/>[cart.ts]"]
end

subgraph group_styles["Styles"]
  node_styles_theme["Theme SCSS<br/>styling<br/>[styles.scss]"]
end

node_pages_index -->|"renders in"| node_layout_main
node_pages_category -->|"renders in"| node_layout_main
node_pages_product -->|"renders in"| node_layout_main
node_pages_cart -->|"renders in"| node_layout_main
node_pages_checkout -->|"renders in"| node_layout_main
node_pages_thankyou -->|"renders in"| node_layout_main
node_pages_cover -->|"renders in"| node_layout_main
node_layout_main -->|"composes"| node_components_header
node_layout_main -->|"composes"| node_components_footer
node_layout_main -->|"composes"| node_components_navigation
node_pages_index -->|"uses"| node_components_catalog
node_pages_category -->|"uses"| node_components_catalog
node_pages_product -->|"uses"| node_components_product
node_pages_cart -->|"uses"| node_components_cart
node_pages_sitemap -->|"uses"| node_lib_domain
node_components_catalog -->|"maps data"| node_lib_domain
node_components_product -->|"maps data"| node_lib_domain
node_components_product -->|"formats"| node_lib_pricing
node_components_cart -->|"reads state"| node_redux_slices
node_components_header -->|"reads state"| node_redux_slices
node_redux_store -->|"assembles"| node_redux_slices
node_pages_index -->|"fetches"| node_lib_api
node_pages_category -->|"fetches"| node_lib_api
node_pages_product -->|"fetches"| node_lib_api
node_pages_cart -->|"fetches"| node_lib_api
node_pages_checkout -->|"bridges"| node_lib_api
node_components_catalog -->|"styled by"| node_styles_theme
node_components_product -->|"styled by"| node_styles_theme
node_components_cart -->|"styled by"| node_styles_theme
node_components_navigation -->|"styled by"| node_styles_theme
node_pages_sitemap -.->|"reads"| node_lib_api

click node_pages_index "https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/pages/index.tsx"
click node_pages_category "https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/pages/category/[slug].tsx"
click node_pages_product "https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/pages/product/[slug].tsx"
click node_pages_cart "https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/pages/cart.tsx"
click node_pages_checkout "https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/pages/checkout/[[...slug]].tsx"
click node_pages_thankyou "https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/pages/thank-you/[id].tsx"
click node_pages_cover "https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/pages/page/cover.tsx"
click node_pages_sitemap "https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/pages/sitemap.xml.ts"
click node_layout_main "https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/layouts/Main.tsx"
click node_components_header "https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/components/Header.tsx"
click node_components_footer "https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/components/Footer.tsx"
click node_components_catalog "https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/components/ProductsList.tsx"
click node_components_product "https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/components/product/PriceAndBuy.tsx"
click node_components_cart "https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/components/cart/CartItems.tsx"
click node_components_navigation "https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/components/HorizontalMenu.tsx"
click node_lib_api "https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/lib/api.ts"
click node_lib_domain "https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/lib/product.ts"
click node_lib_pricing "https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/lib/calculator.ts"
click node_redux_store "https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/redux/store.ts"
click node_redux_slices "https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/redux/reducers/cart.ts"
click node_styles_theme "https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/styles/styles.scss"

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_pages_index,node_pages_category,node_pages_product,node_pages_cart,node_pages_checkout,node_pages_thankyou,node_pages_cover,node_pages_sitemap toneBlue
class node_layout_main,node_components_header,node_components_footer,node_components_catalog,node_components_product,node_components_cart,node_components_navigation toneAmber
class node_lib_api,node_lib_domain,node_lib_pricing toneMint
class node_redux_store,node_redux_slices toneRose
class node_styles_theme toneIndigo
```

## Components

### Pages

Next.js route surfaces and SEO entry points

- [Home](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/pages/index.tsx): route · Storefront landing page · `pages/index.tsx`
- [Category](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/pages/category/[slug].tsx): route · Catalog listing route · `pages/category/[slug].tsx`
- [Product](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/pages/product/[slug].tsx): route · Product detail route · `pages/product/[slug].tsx`
- [Cart](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/pages/cart.tsx): route · Cart page · `pages/cart.tsx`
- [Checkout](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/pages/checkout/[[...slug]].tsx): route · Catch-all checkout bridge · `pages/checkout/[[...slug]].tsx`
- [Thank you](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/pages/thank-you/[id].tsx): route · Post-purchase confirmation route · `pages/thank-you/[id].tsx`
- [CMS page](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/pages/page/cover.tsx): route · Static content page route · `pages/page/cover.tsx`
- [Sitemap](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/pages/sitemap.xml.ts): seo route · Generated sitemap.xml · `pages/sitemap.xml.ts`

### Components

Reusable storefront UI and page composition

- [Main layout](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/layouts/Main.tsx): shell · Shared storefront frame · `layouts/Main.tsx`
- [Header](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/components/Header.tsx): chrome · Top navigation and cart access · `components/Header.tsx`
- [Footer](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/components/Footer.tsx): chrome · Site footer content and links · `components/Footer.tsx`
- [Catalog UI](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/components/ProductsList.tsx): browse ui · Category controls, lists, pagination, and sliders · `components/ProductsList.tsx`
- [Product UI](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/components/product/PriceAndBuy.tsx): product ui · Gallery, variants, pricing, metadata, shipping · `components/product/PriceAndBuy.tsx`
- [Cart UI](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/components/cart/CartItems.tsx): cart ui · Cart rows, loaders, and header widget · `components/cart/CartItems.tsx`
- [Menus](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/components/HorizontalMenu.tsx): navigation · Horizontal, vertical, aside, and breadcrumb navigation · `components/HorizontalMenu.tsx`

### Domain lib

API boundary and presentation-ready data shaping

- [API client](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/lib/api.ts): boundary · Boundless commerce API access · `lib/api.ts`
- [Domain mappers](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/lib/product.ts): transform · Category, product, menu, breadcrumb, meta, and URL shaping · `lib/product.ts`
- [Pricing](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/lib/calculator.ts): calculation · Currency and derived value helpers · `lib/calculator.ts`

### Redux state

Global interactive state and request lifecycle

- [Store](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/redux/store.ts): state container · Redux store composition · `redux/store.ts`
- [Slices](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/redux/reducers/cart.ts): state slices · Cart, alert, aside menu, app, and XHR state · `redux/reducers/cart.ts`

### Styles

SCSS theming and component styling

- [Theme SCSS](https://github.com/kirill-zhirnov/boundless-nextjs-ecommerce-template/blob/master/styles/styles.scss): styling · Global variables, component styles, and sample theme overrides · `styles/styles.scss`

## Connections

- Home → Main layout: renders in · Home page uses shared shell
- Category → Main layout: renders in · Category route uses shared shell
- Product → Main layout: renders in · Product route uses shared shell
- Cart → Main layout: renders in · Cart route uses shared shell
- Checkout → Main layout: renders in · Checkout flow keeps storefront frame
- Thank you → Main layout: renders in · Thank-you page uses shared shell
- CMS page → Main layout: renders in · CMS page uses shared shell
- Main layout → Header: composes · Shared header chrome
- Main layout → Footer: composes · Shared footer chrome
- Main layout → Menus: composes · Global navigation and breadcrumbs
- Home → Catalog UI: uses · Home surfaces merchandising content
- Category → Catalog UI: uses · Category route builds browse experience
- Product → Product UI: uses · Product page builds purchase decision view
- Cart → Cart UI: uses · Cart page shows canonical cart state
- Sitemap → Domain mappers: uses · Sitemap emits canonical URLs and metadata
- Catalog UI → Domain mappers: maps data · Category and list presentation models
- Product UI → Domain mappers: maps data · Product detail transformation and SEO metadata
- Product UI → Pricing: formats · Price display and derived calculations
- Cart UI → Slices: reads state · Cart UI binds to global cart state
- Header → Slices: reads state · Header cart and menu state
- Store → Slices: assembles · Store combines app slices
- Home → API client: fetches · Home content comes from commerce API
- Category → API client: fetches · Category listings come from commerce API
- Product → API client: fetches · Product data comes from commerce API
- Cart → API client: fetches · Cart data is synchronized with backend
- Checkout → API client: bridges · Checkout hands off to Boundless flow
- Catalog UI → Theme SCSS: styled by · Browse UI is SCSS-themed
- Product UI → Theme SCSS: styled by · Product UI is SCSS-themed
- Cart UI → Theme SCSS: styled by · Cart UI is SCSS-themed
- Menus → Theme SCSS: styled by · Menus and breadcrumbs use SCSS styles
- Sitemap → API client: reads · Sitemap may reuse catalog data for URLs
