# bigcommerce/catalyst architecture

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

## Overview

##### Main Components and Their Roles
- Frontend Storefront Application – This is the “core” Next.js app (located in core/app). It handles routing, pages (including dynamic routes for products, accounts, orders, blogs, etc.), API endpoints, and server-side rendering. Subdirectories such as “[locale]”, “api”, and “auth” indicate differentiated flows for authentication, localization, and commerce interactions.
- API and GraphQL Integration – Within the Next.js application, there are API routes (e.g., in core/app/api) that use the GraphQL client (from core/client) to interact with the BigCommerce GraphQL Storefront API. This component manages data fetching, mutations (for cart, authentication, account), and integration with external BigCommerce services.
- Reusable UI Components – Found in directories like core/components and core/vibes, these are tailored React components and primitives (buttons, modals, forms, product cards, etc.) ensuring the storefront is both consistent and customizable.
- Business Logic and Data Transformers – In directories such as core/data-transformers, the project implements business logic to massage data (e.g., for breadcrumbs, product options, search results) to be properly rendered by the UI.
- Middleware and Configuration – The “core/middlewares” and configuration files (e.g., core/next.config.ts, tailwind.config.js, .eslintrc.cjs) show architectural choices for routing, security (CSP headers), and code quality.
- Tooling, CLI, and Package Ecosystem – The monorepo includes a “packages” directory with subprojects like CLI (for project scaffold and build), client (supporting API interactions), and even tooling for linting and configuration (eslint-config-catalyst). These provide extension and automation capabilities across the project.
- Testing and Visual Regression – The “core/tests” directory outlines a comprehensive testing suite that covers both functional and visual regression for UI components and flows.

##### Relationships and Data Flows
- The Next.js frontend acts as the central component. It renders pages by combining reusable UI components with data sourced via API endpoints.
- The API routes (inside the app directory) use the GraphQL client from core/client to fetch data from the external BigCommerce GraphQL Storefront API.
- Middleware modules intercept and enrich requests (for authentication, localization, etc.), ensuring secure and tailored user experiences.
- The CLI and related packages in the “packages” directory interact with the core codebase for scaffolding, setup, and build processes.
- Data transformers act as intermediaries between raw API responses and the UI components, guaranteeing a consistent data model throughout the app.

##### Architectural Patterns and Principles
- Monorepo with Modular Architecture – The project is organized as a monorepo, separating concerns into a core application and various packages for CLI, client libraries, and ESLint configurations.
- Component-Driven and Headless Approach – The storefront is entirely built upon reusable UI components and leverages Next.js server/client components. The headless strategy decouples the presentation from the commerce API.
- Separation of Concerns – With dedicated folders for API, business logic (data transformers), UI, middleware, and testing, the project strictly separates concerns which simplifies scaling and maintenance.
- Extensibility and Customization – Through the CLI and various plugins (for telemetry, localization, etc.), the system design supports high customizability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User("User Request"):::user

    subgraph "Core Application"
        direction TB
        FE("core/app (Frontend Storefront)"):::frontend
        API("core/app/api (API Endpoints)"):::api
    end

    subgraph "GraphQL Integration"
        direction TB
        GraphQL("core/client (GraphQL Client)"):::api
        External("BigCommerce Storefront API"):::external
    end

    subgraph "UI Layer"
        direction TB
        Components("core/components (UI Components)"):::ui
        Vibes("core/vibes (UI Vibes)"):::ui
    end

    Business("core/data-transformers (Data Transformers)"):::logic

    subgraph "Middleware & Configuration"
        direction TB
        Middleware("core/middlewares (Middleware)"):::middleware
        Config("core/next.config.ts (Configuration)"):::middleware
    end

    subgraph "Tooling & Package Ecosystem"
        direction TB
        CLI("packages/cli (CLI Tool)"):::tooling
        ClientPkg("packages/client (Client Package)"):::tooling
        CreateCatalyst("packages/create-catalyst (Scaffolding Tool)"):::tooling
        ESLint("packages/eslint-config-catalyst (ESLint Config)"):::tooling
    end

    Testing("core/tests (Testing Suite)"):::testing

    User -->|"triggers"| FE
    FE -->|"API_Call"| API
    API -->|"fetch_data"| GraphQL
    GraphQL -->|"call_API"| External
    External -->|"data_response"| GraphQL
    GraphQL -->|"forward_data"| API
    API -->|"returns_data"| FE

    API -->|"data_transform"| Business
    Business -->|"supplies_data"| Components
    Business -->|"supplies_data"| Vibes
    
    FE -->|"renders_UI"| Components
    FE -->|"renders_UI"| Vibes

    Middleware -->|"intercepts"| FE
    Middleware -->|"intercepts"| API
    Config -->|"configures"| FE

    CLI -->|"build_scaffold"| FE
    CLI -->|"build_scaffold"| API
    ClientPkg -->|"support"| GraphQL
    CreateCatalyst -->|"setup"| FE
    ESLint -->|"linting"| FE

    Testing -->|"validates"| FE

    classDef user fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef frontend fill:#cce5ff,stroke:#007bff,stroke-width:2px;
    classDef api fill:#d1e7dd,stroke:#0f5132,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#842029,stroke-width:2px;
    classDef ui fill:#d1c4e9,stroke:#6f42c1,stroke-width:2px;
    classDef logic fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef middleware fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef tooling fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef testing fill:#fefefe,stroke:#6c757d,stroke-width:2px;

    click FE "https://github.com/bigcommerce/catalyst/tree/canary/core/app"
    click API "https://github.com/bigcommerce/catalyst/tree/canary/core/app/api"
    click GraphQL "https://github.com/bigcommerce/catalyst/tree/canary/core/client"
    click Components "https://github.com/bigcommerce/catalyst/tree/canary/core/components"
    click Vibes "https://github.com/bigcommerce/catalyst/tree/canary/core/vibes"
    click Business "https://github.com/bigcommerce/catalyst/tree/canary/core/data-transformers"
    click Middleware "https://github.com/bigcommerce/catalyst/tree/canary/core/middlewares"
    click Config "https://github.com/bigcommerce/catalyst/blob/canary/core/next.config.ts"
    click CLI "https://github.com/bigcommerce/catalyst/tree/canary/packages/cli"
    click ClientPkg "https://github.com/bigcommerce/catalyst/tree/canary/packages/client"
    click CreateCatalyst "https://github.com/bigcommerce/catalyst/tree/canary/packages/create-catalyst"
    click ESLint "https://github.com/bigcommerce/catalyst/tree/canary/packages/eslint-config-catalyst"
    click Testing "https://github.com/bigcommerce/catalyst/tree/canary/core/tests"
```
