# bigcommerce-labs/catalyst-makeswift architecture

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

- Interactive diagram: https://gitdiagram.com/bigcommerce-labs/catalyst-makeswift
- Repository: https://github.com/bigcommerce-labs/catalyst-makeswift

## Overview

1. **Overall shape**
   - This is a **Next.js App Router** storefront for **BigCommerce Catalyst**, not a generic web app.
   - The app is organized around localized routes under `app/[locale]`, with most business logic split between route-specific `page-data.ts`, route UI components, and shared storefront primitives.

2. **Primary external systems**
   - The main backend dependency is **BigCommerce GraphQL Storefront API**.
   - Additional integrations include **NextAuth** for authentication/session handling, **Makeswift** for CMS-style page editing/draft mode, and a **KV store** abstraction for ephemeral state or caching.
   - The README and directory structure indicate this repo is meant to be connected to a specific BigCommerce store/channel via environment configuration.

3. **Request routing and edge middleware**
   - The top-level `middleware.ts` is composed from `middlewares/compose-middlewares.ts` and specialized middlewares such as `with-auth`, `with-makeswift`, and `with-routes`.
   - This is the first boundary in the system: requests are normalized for locale, auth, and editor/draft behavior before hitting page handlers.
   - `navigation.ts`, `i18n.ts`, and `messages/*.json` support localized routing and translated UI strings.

4. **Localized storefront pages**
   - The main customer-facing experience lives under `app/[locale]/(default)`, which contains route groups for:
     - catalog browsing (`product`, `category`, `brand`, `search`, faceted listing),
     - commerce flows (`cart`, `compare`, `login`, `account`),
     - content pages (`blog`, `webpages`, static pages),
     - and utility pages like `maintenance`, `error`, and `not-found`.
   - Many routes have companion `page-data.ts` files, which are the data-fetching boundary between the route and the API client layer.

5. **Data access layer**
   - The `client/` folder is the main API boundary to BigCommerce.
   - It is split into:
     - `client/queries` for read operations,
     - `client/mutations` for write operations,
     - `client/fragments` for reusable GraphQL selection sets,
     - `client/management` for auxiliary store-management lookups like countries and zones.
   - This layer centralizes all storefront API interaction so pages and components do not talk to BigCommerce directly.

6. **Server actions and commerce mutations**
   - Many interactive flows use route-local `_actions` files, especially in `cart`, `account`, `login`, `compare`, and product/cart components.
   - These actions typically orchestrate a mutation in `client/mutations`, then trigger revalidation or redirect behavior.
   - This is the key write-path in the architecture: user interaction → server action → GraphQL mutation → refreshed storefront state.

7. **Cart, checkout, and customer flows**
   - The cart subsystem is rich and self-contained, with components for line items, quantity updates, coupon handling, shipping estimation, shipping option selection, and checkout redirect.
   - Customer identity flows are split between login/register/reset-password and authenticated account management.
   - Account pages manage addresses and profile settings via dedicated actions and forms under `app/[locale]/(default)/account/[tab]`.

8. **Catalog and product presentation**
   - Product and category pages are built from specialized component bundles in their route directories, with shared faceting/search pieces under `(faceted)`.
   - Product pages use fragments and subcomponents for gallery, description, details, reviews, related products, and structured data/schema output.
   - Category, brand, and search pages share a faceted navigation model, suggesting a common result-listing pipeline with filters, sorting, pagination, and mobile navigation.

9. **Reusable storefront component system**
   - `components/` contains shared UI and domain components used across routes.
   - There is a clear separation between:
     - low-level `components/ui/*` design-system primitives,
     - higher-level storefront widgets like header, footer, breadcrumbs, hero, product card, quick search, compare drawer, and product sheet,
     - and form systems like `product-form`.
   - This makes the route pages thin composition layers rather than monolithic UI implementations.

10. **Content, CMS, and draft-mode integration**
   - Makeswift support is first-class, with `app/api/makeswift/*`, `makeswift/*`, and middleware support.
   - Content-heavy routes such as pages, blog posts, and “webpages” likely blend BigCommerce content data with Makeswift-rendered or draftable content.
   - This is an important architectural boundary: dynamic storefront commerce flows coexist with CMS-driven marketing pages.

11. **API routes**
   - `app/api/auth/[...nextauth]/route.ts` exposes auth endpoints.
   - `app/api/cart-quantity/route.ts` likely supports cart badge/count updates.
   - `app/api/product/[id]/route.ts` provides a product-level API surface, probably for product detail or quick lookup behavior.
   - `app/api/internal-auth.ts` suggests internal request protection for select endpoints or integrations.

12. **State, caching, and infrastructure utilities**
   - `lib/kv` provides a storage abstraction with memory and Vercel adapters, indicating the app can run both locally and in hosted/serverless environments.
   - `lib/cdn-image-loader.ts`, `lib/store-assets.ts`, and `lib/utils.ts` hold shared infrastructure helpers for asset delivery and common transformations.
   - `client/revalidate-target.ts` and `client/tags.ts` indicate revalidation/invalidation is part of the data freshness strategy.

13. **Runtime characteristics**
   - The repo is TypeScript-first and uses modern Next.js conventions with server components, server actions, localized route segments, and route-level composition.
   - It is designed for Node.js 20+ and deployed as a storefront, where render-time data fetching and cache invalidation matter more than traditional client-side state management.

Main entry points: [`app/[locale]/(default)`](https://github.com/bigcommerce-labs/catalyst-makeswift/tree/main/app/[locale]/(default)) (Storefront routes), [`components`](https://github.com/bigcommerce-labs/catalyst-makeswift/tree/main/components) (Shared UI), [`middlewares/compose-middlewares.ts`](https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/middlewares/compose-middlewares.ts) (Compose), [`client`](https://github.com/bigcommerce-labs/catalyst-makeswift/tree/main/client) (BigCommerce client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routing["Routing & entry"]
  node_middleware["Middleware<br/>request pipeline<br/>[middleware.ts]"]
  node_compose_middlewares["Compose"]
  node_with_auth["Auth guard<br/>middleware<br/>[with-auth.ts]"]
  node_with_makeswift["Makeswift mw<br/>middleware<br/>[with-makeswift.ts]"]
  node_with_routes["Route rules<br/>middleware<br/>[with-routes.ts]"]
  node_locale_app["Locale app<br/>app shell<br/>[layout.tsx]"]
end

subgraph group_storefront["Storefront UI"]
  node_default_routes["Storefront routes<br/>route segment"]
  node_faceted_catalog["Faceted catalog<br/>catalog subsystem"]
  node_product_page["Product page<br/>product route<br/>[page.tsx]"]
  node_cart_flow["Cart flow<br/>commerce route<br/>[page.tsx]"]
  node_account_flow["Account flow<br/>customer route<br/>[page.tsx]"]
  node_login_flow["Login flow<br/>identity route<br/>[page.tsx]"]
  node_content_pages["Content pages<br/>content route<br/>[page.tsx]"]
  node_shared_components["Shared UI<br/>component library"]
end

subgraph group_data["Data layer"]
  node_client_api[("BigCommerce client<br/>graphql boundary")]
  node_server_actions["Server actions<br/>write orchestration"]
  node_revalidate_tags["Revalidation<br/>cache control"]
end

subgraph group_integrations["External integrations"]
  node_kv_store[("KV store<br/>ephemeral storage")]
  node_makeswift_runtime["Makeswift<br/>cms integration"]
  node_nextauth_api["NextAuth API<br/>auth integration<br/>[route.ts]"]
end

node_middleware -->|"uses"| node_compose_middlewares
node_compose_middlewares -->|"includes"| node_with_auth
node_compose_middlewares -->|"includes"| node_with_makeswift
node_compose_middlewares -->|"includes"| node_with_routes
node_middleware -->|"protects"| node_locale_app
node_locale_app -->|"contains"| node_default_routes
node_default_routes -->|"shares"| node_faceted_catalog
node_default_routes -->|"contains"| node_product_page
node_default_routes -->|"contains"| node_cart_flow
node_default_routes -->|"contains"| node_account_flow
node_default_routes -->|"contains"| node_login_flow
node_default_routes -->|"contains"| node_content_pages
node_faceted_catalog -->|"queries"| node_client_api
node_product_page -->|"queries"| node_client_api
node_cart_flow -->|"writes via"| node_server_actions
node_account_flow -->|"writes via"| node_server_actions
node_login_flow -->|"writes via"| node_server_actions
node_server_actions -->|"mutates"| node_client_api
node_server_actions -->|"invalidates"| node_revalidate_tags
node_client_api -->|"uses"| node_kv_store
node_content_pages -->|"renders with"| node_makeswift_runtime
node_middleware -->|"enables"| node_makeswift_runtime
node_nextauth_api -->|"supports"| node_with_auth
node_shared_components -->|"used by"| node_product_page
node_shared_components -->|"used by"| node_cart_flow
node_shared_components -->|"used by"| node_faceted_catalog
node_shared_components -->|"used by"| node_content_pages

click node_middleware "https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/middleware.ts"
click node_compose_middlewares "https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/middlewares/compose-middlewares.ts"
click node_with_auth "https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/middlewares/with-auth.ts"
click node_with_makeswift "https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/middlewares/with-makeswift.ts"
click node_with_routes "https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/middlewares/with-routes.ts"
click node_locale_app "https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/app/[locale]/layout.tsx"
click node_default_routes "https://github.com/bigcommerce-labs/catalyst-makeswift/tree/main/app/[locale]/(default)"
click node_faceted_catalog "https://github.com/bigcommerce-labs/catalyst-makeswift/tree/main/app/[locale]/(default)/(faceted)"
click node_product_page "https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/app/[locale]/(default)/product/[slug]/page.tsx"
click node_cart_flow "https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/app/[locale]/(default)/cart/page.tsx"
click node_account_flow "https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/app/[locale]/(default)/account/[tab]/page.tsx"
click node_login_flow "https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/app/[locale]/(default)/login/page.tsx"
click node_content_pages "https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/app/[locale]/(default)/blog/page.tsx"
click node_shared_components "https://github.com/bigcommerce-labs/catalyst-makeswift/tree/main/components"
click node_client_api "https://github.com/bigcommerce-labs/catalyst-makeswift/tree/main/client"
click node_server_actions "https://github.com/bigcommerce-labs/catalyst-makeswift/tree/main/app/[locale]/(default)"
click node_revalidate_tags "https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/client/revalidate-target.ts"
click node_kv_store "https://github.com/bigcommerce-labs/catalyst-makeswift/tree/main/lib/kv"
click node_makeswift_runtime "https://github.com/bigcommerce-labs/catalyst-makeswift/tree/main/makeswift"
click node_nextauth_api "https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/app/api/auth/[...nextauth]/route.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_middleware,node_compose_middlewares,node_with_auth,node_with_makeswift,node_with_routes,node_locale_app toneBlue
class node_default_routes,node_faceted_catalog,node_product_page,node_cart_flow,node_account_flow,node_login_flow,node_content_pages,node_shared_components toneAmber
class node_client_api,node_server_actions,node_revalidate_tags toneMint
class node_kv_store,node_makeswift_runtime,node_nextauth_api toneRose
```

## Components

### Routing & entry

Locale-aware request handling, middleware, and top-level app shell.

- [Middleware](https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/middleware.ts): request pipeline · Composes locale, auth, Makeswift, and route handling before pages run. · `middleware.ts`
- [Compose](https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/middlewares/compose-middlewares.ts): middleware composer · Builds the middleware chain used at the edge boundary. · `middlewares/compose-middlewares.ts`
- [Auth guard](https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/middlewares/with-auth.ts): middleware · Adds session/auth behavior to requests. · `middlewares/with-auth.ts`
- [Makeswift mw](https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/middlewares/with-makeswift.ts): middleware · Enables draft/editor behavior for CMS-driven pages. · `middlewares/with-makeswift.ts`
- [Route rules](https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/middlewares/with-routes.ts): middleware · Applies route normalization and rewrite logic. · `middlewares/with-routes.ts`
- [Locale app](https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/app/[locale]/layout.tsx): app shell · Locale-scoped application root and nested default storefront segment. · `app/[locale]/layout.tsx`

### Storefront UI

Customer-facing routes and shared storefront components.

- [Storefront routes](https://github.com/bigcommerce-labs/catalyst-makeswift/tree/main/app/[locale]/(default)): route segment · Main localized customer experience under the default route group. · `app/[locale]/(default)`
- [Faceted catalog](https://github.com/bigcommerce-labs/catalyst-makeswift/tree/main/app/[locale]/(default)/(faceted)): catalog subsystem · Shared browsing pipeline for category, brand, and search result pages. · `app/[locale]/(default)/(faceted)`
- [Product page](https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/app/[locale]/(default)/product/[slug]/page.tsx): product route · Localized product detail experience with media, reviews, and schema output. · `app/[locale]/(default)/product/[slug]/page.tsx`
- [Cart flow](https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/app/[locale]/(default)/cart/page.tsx): commerce route · Cart view plus quantity, coupon, shipping, and checkout actions. · `app/[locale]/(default)/cart/page.tsx`
- [Account flow](https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/app/[locale]/(default)/account/[tab]/page.tsx): customer route · Authenticated account pages for profile and address management. · `app/[locale]/(default)/account/[tab]/page.tsx`
- [Login flow](https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/app/[locale]/(default)/login/page.tsx): identity route · Login, register, reset password, and customer password actions. · `app/[locale]/(default)/login/page.tsx`
- [Content pages](https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/app/[locale]/(default)/blog/page.tsx): content route · Blog, webpages, static pages, and localized content routing. · `app/[locale]/(default)/blog/page.tsx`
- [Shared UI](https://github.com/bigcommerce-labs/catalyst-makeswift/tree/main/components): component library · Reusable storefront components and UI primitives used across routes. · `components`

### Data layer

BigCommerce API access, server actions, caching, and revalidation.

- [BigCommerce client](https://github.com/bigcommerce-labs/catalyst-makeswift/tree/main/client): graphql boundary · Central GraphQL API layer with queries, mutations, fragments, and management lookups. · `client`
- [Server actions](https://github.com/bigcommerce-labs/catalyst-makeswift/tree/main/app/[locale]/(default)): write orchestration · Route-local actions that call mutations and then refresh or redirect. · `app/[locale]/(default)`
- [Revalidation](https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/client/revalidate-target.ts): cache control · Target and tag helpers used to invalidate storefront data after writes. · `client/revalidate-target.ts`

### External integrations

Auth, CMS/draft mode, and runtime adapters.

- [KV store](https://github.com/bigcommerce-labs/catalyst-makeswift/tree/main/lib/kv): ephemeral storage · Memory and Vercel adapters for short-lived state and caching. · `lib/kv`
- [Makeswift](https://github.com/bigcommerce-labs/catalyst-makeswift/tree/main/makeswift): cms integration · Client, provider, and runtime support for draft-mode editing and rendered content. · `makeswift`
- [NextAuth API](https://github.com/bigcommerce-labs/catalyst-makeswift/blob/main/app/api/auth/[...nextauth]/route.ts): auth integration · Authentication endpoints and session handling for customer flows. · `app/api/auth/[...nextauth]/route.ts`

## Connections

- Middleware → Compose: uses · The top-level middleware is assembled from shared middleware composition.
- Compose → Auth guard: includes · Auth behavior is one step in the request pipeline.
- Compose → Makeswift mw: includes · Draft/editor handling is added to the request pipeline.
- Compose → Route rules: includes · Route normalization and rewrites are layered into the pipeline.
- Middleware → Locale app: protects · Requests are normalized before entering the locale-scoped app.
- Locale app → Storefront routes: contains · The locale root hosts the main storefront segment.
- Storefront routes → Faceted catalog: shares · Category, brand, and search routes reuse the faceted browsing subsystem.
- Storefront routes → Product page: contains · Product detail routes live in the default storefront segment.
- Storefront routes → Cart flow: contains · Cart and checkout-related screens live in the storefront segment.
- Storefront routes → Account flow: contains · Customer account pages are part of the default storefront segment.
- Storefront routes → Login flow: contains · Customer identity routes are part of the storefront flow.
- Storefront routes → Content pages: contains · Blog, webpages, and static content routes live alongside commerce routes.
- Faceted catalog → BigCommerce client: queries · Catalog list pages fetch product and route data through the API layer.
- Product page → BigCommerce client: queries · Product detail pages read product data and fragments from BigCommerce.
- Cart flow → Server actions: writes via · Cart interactions are mediated by server actions.
- Account flow → Server actions: writes via · Profile and address updates are executed through route-local actions.
- Login flow → Server actions: writes via · Login, registration, and password flows are handled by server actions.
- Server actions → BigCommerce client: mutates · Actions orchestrate GraphQL mutations against the storefront API.
- Server actions → Revalidation: invalidates · Successful writes refresh cached storefront data.
- BigCommerce client → KV store: uses · Supporting infrastructure can persist ephemeral state through KV adapters.
- Content pages → Makeswift: renders with · Marketing and content pages can be powered by Makeswift runtime and draft mode.
- Middleware → Makeswift: enables · Middleware activates Makeswift draft/editor behavior.
- NextAuth API → Auth guard: supports · NextAuth endpoints back the auth middleware and customer sessions.
- Shared UI → Product page: used by · Shared product, sheet, gallery, and schema components assemble product pages.
- Shared UI → Cart flow: used by · Header, cart, and form primitives support cart interactions.
- Shared UI → Faceted catalog: used by · Facets, search, and listing UI build catalog browsing.
- Shared UI → Content pages: used by · Global UI primitives and content widgets support blog and webpage rendering.
