# bigcommerce/b2b-buyer-portal architecture

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

- Interactive diagram: https://gitdiagram.com/bigcommerce/b2b-buyer-portal
- Repository: https://github.com/bigcommerce/b2b-buyer-portal

## Overview

##### Main Components
- Frontend Application (Storefront): The core of the project resides in the “apps/storefront” workspace. This is the next‐gen buyer portal built in React and includes the pages (e.g., Login, Dashboard, Invoice, Quote, etc.), a host of React components (buttons, dialogs, forms, etc.), custom hooks, state management (e.g., in the “store” folder), and a variety of utilities.
- Shared Packages & Libraries: Under “packages” you have several workspaces:
– ESLint configurations (eslint-config-b3, etc.).
– Shared TypeScript configurations (“tsconfig”).
– UI Components and Shared Store logic (e.g., packages/ui, packages/store, packages/global-b3).
– Language and utilities packages (packages/lang, packages/utils, packages/hooks).
- CI/CD & Build Infrastructure: The integration files in .circleci, .github/workflows, plus configuration files like “turbo.json”, “vite.config.ts”, and various deployment/config scripts in the “config” and “deployment” directories represent the automated build, deployment, and development infrastructure.
- Documentation & Development Guides: The “docs” folder, README, and RFC materials help document the architectural decisions and provide usage guidelines.

##### Relationships and Interactions
- The “Storefront” acts as the central user-facing component. It renders pages built with reusable components from the “src/components” directories and organizes application routing using React Router.
- Custom hooks and state management (in “src/hooks” and “src/store”) supply business logic and manage app-level state.
- Shared libraries and utilities (under “packages”) are imported into the storefront and other possible packages to enforce consistency (e.g., TypeScript settings from “packages/tsconfig”, UI components from “packages/ui”, language support from “packages/lang”).
- CI/CD workflows (in .github/workflows and .circleci) connect to deployment pipelines and automated tests, ensuring quality and ease of delivery.
- External integrations are implied: while not explicitly depicted in internal code, the README points to connectivity with BigCommerce SaaS APIs and external storefront settings (e.g., header/footer scripts, cross-origin configuration).

##### Important Architectural Patterns and Design Principles
- Modularity: The monorepo structure (using Turborepo) clearly separates the frontend application from shared packages and configuration.
- Reusability: Extensive use of reusable components, hooks, and shared modules in “packages” minimizes duplication and eases maintenance.
- Separation of Concerns: Dividing code into pages, components, hooks, store logic, and utilities enables clear responsibilities and easier testing.
- CI/CD Integration: With dedicated directories and configuration files for deployment and testing, the project embraces continuous integration and continuous deployment practices.

– Pages: Represented as submodules (Login, Dashboard, Account Settings, Orders, etc.).
– UI / Component Library: A layer containing common components, form controls, dialogs, and layout components.
– State Management: Include a separate section for the redux-like store slices or context providers (see “src/store”).
– Custom Hooks and Utilities: Represent the logic components that handle business rules, API calls, and formatting (all under “src/hooks” and “src/utils”).
– ESLint Configurations, TSConfig, Language, and other utilities.
- On the far external side, include “External Services” to denote BigCommerce SaaS APIs and the integration points with store endpoints (as described in the README).
– Data flow from user interactions in the browser to the Storefront UI components.
– Dependencies from Storefront to Shared Packages.
– Integration with CI/CD pipelines that trigger builds/tests/deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    UB["User Browser"]:::external

    %% Main Application: B2B Buyer Portal (Storefront)
    subgraph "B2B Buyer Portal (Storefront)"
        direction TB
        S["Storefront"]:::storefront

        %% Presentation Layer
        subgraph "Presentation Layer"
            direction TB
            P["Pages"]:::storefront
            C["UI Components"]:::storefront
        end

        %% Logic & State Layer
        subgraph "Logic & State"
            direction TB
            H["Custom Hooks & Business Logic"]:::storefront
            ST["State Management"]:::storefront
        end
    end

    %% Shared Packages & Configurations
    subgraph "Shared Packages & Configurations"
        direction TB
        ESL1["ESLint Config b2b"]:::config
        ESL2["ESLint Config bc"]:::config
        TSC["Shared TS Configs"]:::config
        GLOB["UI Components & Global Logic"]:::config
        LANG["Language Support"]:::config
        UTIL["Utilities"]:::config
        SHOOKS["Shared Hooks"]:::config
    end

    %% CI/CD & Build Infrastructure
    subgraph "CI/CD & Build Infrastructure"
        direction TB
        CIRC[".circleci"]:::cicd
        GHWF[".github/workflows"]:::cicd
        DEPLOY["Config/Deploy"]:::cicd
        DEPLOY2["Deployment"]:::cicd
        TURBO["Turbo Config"]:::cicd
        VITE["Vite Config"]:::cicd
    end

    %% Documentation & Development Guides
    subgraph "Documentation & Guides"
        direction TB
        DOCS["Docs"]:::docs
        RFC["RFC"]:::docs
        READ["README"]:::docs
    end

    %% External Services
    EXTS["BigCommerce SaaS APIs"]:::external

    %% Relationships
    UB -->|"loads"| P
    S -->|"renders"| P
    S -->|"renders"| C
    P -->|"invokes"| H
    P -->|"updates"| ST
    S -->|"depends on"| ESL1
    S -->|"depends on"| ESL2
    S -->|"depends on"| TSC
    S -->|"depends on"| GLOB
    S -->|"depends on"| LANG
    S -->|"depends on"| UTIL
    S -->|"depends on"| SHOOKS
    C -->|"uses"| H
    H -->|"manages"| ST

    CIRC --- GHWF
    GHWF --- DEPLOY
    DEPLOY --- DEPLOY2
    DEPLOY2 --- TURBO
    TURBO --- VITE

    CIRC --- S
    GHWF --- S
    DEPLOY --- S
    DEPLOY2 --- S
    TURBO --- S
    VITE --- S

    S --- EXTS
    DOCS --- S
    RFC --- S
    READ --- S

    %% Click Events for Storefront Application and Sub-components
    click S "https://github.com/bigcommerce/b2b-buyer-portal/tree/main/apps/storefront"
    click P "https://github.com/bigcommerce/b2b-buyer-portal/tree/main/apps/storefront/src/pages"
    click C "https://github.com/bigcommerce/b2b-buyer-portal/tree/main/apps/storefront/src/components"
    click H "https://github.com/bigcommerce/b2b-buyer-portal/tree/main/apps/storefront/src/hooks"
    click ST "https://github.com/bigcommerce/b2b-buyer-portal/tree/main/apps/storefront/src/store"

    %% Click Events for Shared Packages & Configurations
    click ESL1 "https://github.com/bigcommerce/b2b-buyer-portal/tree/main/packages/eslint-config-b2b"
    click ESL2 "https://github.com/bigcommerce/b2b-buyer-portal/tree/main/packages/eslint-config-bc"
    click TSC "https://github.com/bigcommerce/b2b-buyer-portal/tree/main/packages/tsconfig"
    click GLOB "https://github.com/bigcommerce/b2b-buyer-portal/tree/main/packages/global-b3"
    click LANG "https://github.com/bigcommerce/b2b-buyer-portal/tree/main/packages/lang"
    click UTIL "https://github.com/bigcommerce/b2b-buyer-portal/tree/main/packages/utils"
    click SHOOKS "https://github.com/bigcommerce/b2b-buyer-portal/tree/main/packages/hooks"

    %% Click Events for CI/CD & Build Infrastructure
    click CIRC "https://github.com/bigcommerce/b2b-buyer-portal/blob/main/.circleci"
    click GHWF "https://github.com/bigcommerce/b2b-buyer-portal/tree/main/.github/workflows"
    click DEPLOY "https://github.com/bigcommerce/b2b-buyer-portal/tree/main/config/deploy"
    click DEPLOY2 "https://github.com/bigcommerce/b2b-buyer-portal/tree/main/deployment"
    click TURBO "https://github.com/bigcommerce/b2b-buyer-portal/blob/main/turbo.json"
    click VITE "https://github.com/bigcommerce/b2b-buyer-portal/blob/main/apps/storefront/vite.config.ts"

    %% Click Events for Documentation & Guides
    click DOCS "https://github.com/bigcommerce/b2b-buyer-portal/tree/main/docs"
    click RFC "https://github.com/bigcommerce/b2b-buyer-portal/tree/main/rfc"
    click READ "https://github.com/bigcommerce/b2b-buyer-portal/blob/main/README.md"

    %% Styles
    classDef storefront fill:#ADD8E6,stroke:#000,stroke-width:2px
    classDef config fill:#C1E1C1,stroke:#000,stroke-width:2px,stroke-dasharray: 5 5
    classDef cicd fill:#F7D6AD,stroke:#000,stroke-width:2px,stroke-dasharray: 3 3
    classDef docs fill:#EAD1DC,stroke:#000,stroke-width:2px,stroke-dasharray: 2 2
    classDef external fill:#F2A7A7,stroke:#000,stroke-width:2px
```
