# bigcommerce/checkout-js architecture

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

- Interactive diagram: https://gitdiagram.com/bigcommerce/checkout-js
- Repository: https://github.com/bigcommerce/checkout-js

## Overview

Checkout JS is BigCommerce’s browser-based, one-page checkout for shoppers. The principal workflow is entering customer, address, shipping, and payment details and completing checkout; the README establishes the shopper-facing purpose, while the tree shows the distinct checkout stages and payment-provider integrations. The graph also highlights checkout context, hosted card fields, and extension handling as internal layers. Most implementation files were not sampled, so links between checkout stages and provider packages are omitted rather than inferred; extension and hosted-card links reflect the supplied source excerpts.

Main entry points: [`packages/checkout-extension/src/ExtensionService.ts`](https://github.com/bigcommerce/checkout-js/blob/master/packages/checkout-extension/src/ExtensionService.ts) (Extension service), [`packages/hosted-credit-card-integration/src/hooks/useHostedCreditCard.tsx`](https://github.com/bigcommerce/checkout-js/blob/master/packages/hosted-credit-card-integration/src/hooks/useHostedCreditCard.tsx) (Hosted card fields), [`packages/core/src/app/checkout/CheckoutApp.tsx`](https://github.com/bigcommerce/checkout-js/blob/master/packages/core/src/app/checkout/CheckoutApp.tsx) (Checkout app), [`packages/checkout-extension/src/handler/commandHandlers/index.ts`](https://github.com/bigcommerce/checkout-js/blob/master/packages/checkout-extension/src/handler/commandHandlers/index.ts) (Extension handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_checkout["Checkout experience"]
  node_checkout_app["Checkout app<br/>[CheckoutApp.tsx]"]
  node_checkout_steps["Checkout steps<br/>[CheckoutStep.tsx]"]
  node_cart_summary["Cart summary<br/>[CartSummary.tsx]"]
  node_billing["Billing<br/>[Billing.tsx]"]
  node_shipping["Shipping<br/>[useShipping.ts]"]
  node_coupon_management["Coupons and gifts"]
  node_payment_step["Payment step<br/>[PaymentStep.tsx]"]
end

subgraph group_customer["Customer and addresses"]
  node_customer_details["Customer details<br/>[Customer.tsx]"]
  node_address_forms["Address forms<br/>[AddressForm.tsx]"]
  node_company_search["Company address search"]
end

subgraph group_payments["Payment methods"]
  node_payment_api["Payment form API"]
  node_hosted_card["Hosted card fields"]
  node_card_methods["Card integrations"]
  node_wallet_methods["Wallet integrations"]
  node_provider_methods["Provider integrations"]
end

subgraph group_platform["Checkout platform"]
  node_checkout_context["Checkout context<br/>[useCheckout.tsx]"]
  node_extension_service["Extension service"]
  node_extension_handlers["Extension handlers<br/>[index.ts]"]
  node_extension_queries["Extension queries<br/>[QueryHandler.ts]"]
  node_extension_regions["Extension regions"]
end

node_shopper(("Shopper"))

node_shopper -->|"uses"| node_checkout_app
node_checkout_app -->|"checkout UI"| node_shopper
node_company_search -->|"gets service"| node_checkout_context
node_hosted_card -.->|"uses form"| node_payment_api
node_hosted_card -->|"renders validation"| node_extension_handlers
node_extension_service -->|"registers commands"| node_extension_handlers
node_extension_service -->|"registers queries"| node_extension_queries
node_extension_service -.->|"renders region"| node_extension_regions

click node_checkout_app "https://github.com/bigcommerce/checkout-js/blob/master/packages/core/src/app/checkout/CheckoutApp.tsx"
click node_checkout_steps "https://github.com/bigcommerce/checkout-js/blob/master/packages/core/src/app/checkout/CheckoutStep.tsx"
click node_cart_summary "https://github.com/bigcommerce/checkout-js/blob/master/packages/core/src/app/cart/CartSummary.tsx"
click node_billing "https://github.com/bigcommerce/checkout-js/blob/master/packages/core/src/app/billing/Billing.tsx"
click node_shipping "https://github.com/bigcommerce/checkout-js/blob/master/packages/core/src/app/shipping/hooks/useShipping.ts"
click node_customer_details "https://github.com/bigcommerce/checkout-js/blob/master/packages/core/src/app/customer/Customer.tsx"
click node_address_forms "https://github.com/bigcommerce/checkout-js/blob/master/packages/core/src/app/address/AddressForm.tsx"
click node_company_search "https://github.com/bigcommerce/checkout-js/blob/master/packages/core/src/app/address/useCompanyAddressSearch.ts"
click node_coupon_management "https://github.com/bigcommerce/checkout-js/blob/master/packages/core/src/app/coupon/components/ManageCouponsAndGiftCertificates.tsx"
click node_payment_step "https://github.com/bigcommerce/checkout-js/blob/master/packages/core/src/app/checkout/components/PaymentStep.tsx"
click node_payment_api "https://github.com/bigcommerce/checkout-js/blob/master/packages/payment-integration-api/src/PaymentFormService.ts"
click node_hosted_card "https://github.com/bigcommerce/checkout-js/blob/master/packages/hosted-credit-card-integration/src/hooks/useHostedCreditCard.tsx"
click node_card_methods "https://github.com/bigcommerce/checkout-js/blob/master/packages/credit-card-integration/src/CreditCardPaymentMethodComponent.tsx"
click node_wallet_methods "https://github.com/bigcommerce/checkout-js/blob/master/packages/apple-pay-integration/src/ApplePayPaymentMethod.tsx"
click node_provider_methods "https://github.com/bigcommerce/checkout-js/blob/master/packages/adyen-integration/src/adyenv3/AdyenV3PaymentMethod.tsx"
click node_checkout_context "https://github.com/bigcommerce/checkout-js/blob/master/packages/contexts/src/checkout/useCheckout.tsx"
click node_extension_service "https://github.com/bigcommerce/checkout-js/blob/master/packages/checkout-extension/src/ExtensionService.ts"
click node_extension_handlers "https://github.com/bigcommerce/checkout-js/blob/master/packages/checkout-extension/src/handler/commandHandlers/index.ts"
click node_extension_queries "https://github.com/bigcommerce/checkout-js/blob/master/packages/checkout-extension/src/handler/queryHandlers/QueryHandler.ts"
click node_extension_regions "https://github.com/bigcommerce/checkout-js/blob/master/packages/checkout-extension/src/ExtensionRegionContainer.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_checkout_app,node_checkout_steps,node_cart_summary,node_billing,node_shipping,node_coupon_management,node_payment_step toneBlue
class node_customer_details,node_address_forms,node_company_search toneAmber
class node_payment_api,node_hosted_card,node_card_methods,node_wallet_methods,node_provider_methods toneMint
class node_checkout_context,node_extension_service,node_extension_handlers,node_extension_queries,node_extension_regions toneRose
class node_shopper toneIndigo
```

## Components

### Checkout experience

- [Checkout app](https://github.com/bigcommerce/checkout-js/blob/master/packages/core/src/app/checkout/CheckoutApp.tsx): `packages/core/src/app/checkout/CheckoutApp.tsx`
- [Checkout steps](https://github.com/bigcommerce/checkout-js/blob/master/packages/core/src/app/checkout/CheckoutStep.tsx): `packages/core/src/app/checkout/CheckoutStep.tsx`
- [Cart summary](https://github.com/bigcommerce/checkout-js/blob/master/packages/core/src/app/cart/CartSummary.tsx): `packages/core/src/app/cart/CartSummary.tsx`
- [Billing](https://github.com/bigcommerce/checkout-js/blob/master/packages/core/src/app/billing/Billing.tsx): `packages/core/src/app/billing/Billing.tsx`
- [Shipping](https://github.com/bigcommerce/checkout-js/blob/master/packages/core/src/app/shipping/hooks/useShipping.ts): `packages/core/src/app/shipping/hooks/useShipping.ts`
- [Coupons and gifts](https://github.com/bigcommerce/checkout-js/blob/master/packages/core/src/app/coupon/components/ManageCouponsAndGiftCertificates.tsx): `packages/core/src/app/coupon/components/ManageCouponsAndGiftCertificates.tsx`
- [Payment step](https://github.com/bigcommerce/checkout-js/blob/master/packages/core/src/app/checkout/components/PaymentStep.tsx): `packages/core/src/app/checkout/components/PaymentStep.tsx`

### Customer and addresses

- [Customer details](https://github.com/bigcommerce/checkout-js/blob/master/packages/core/src/app/customer/Customer.tsx): `packages/core/src/app/customer/Customer.tsx`
- [Address forms](https://github.com/bigcommerce/checkout-js/blob/master/packages/core/src/app/address/AddressForm.tsx): `packages/core/src/app/address/AddressForm.tsx`
- [Company address search](https://github.com/bigcommerce/checkout-js/blob/master/packages/core/src/app/address/useCompanyAddressSearch.ts): `packages/core/src/app/address/useCompanyAddressSearch.ts`

### Payment methods

- [Payment form API](https://github.com/bigcommerce/checkout-js/blob/master/packages/payment-integration-api/src/PaymentFormService.ts): `packages/payment-integration-api/src/PaymentFormService.ts`
- [Hosted card fields](https://github.com/bigcommerce/checkout-js/blob/master/packages/hosted-credit-card-integration/src/hooks/useHostedCreditCard.tsx): `packages/hosted-credit-card-integration/src/hooks/useHostedCreditCard.tsx`
- [Card integrations](https://github.com/bigcommerce/checkout-js/blob/master/packages/credit-card-integration/src/CreditCardPaymentMethodComponent.tsx): `packages/credit-card-integration/src/CreditCardPaymentMethodComponent.tsx`
- [Wallet integrations](https://github.com/bigcommerce/checkout-js/blob/master/packages/apple-pay-integration/src/ApplePayPaymentMethod.tsx): `packages/apple-pay-integration/src/ApplePayPaymentMethod.tsx`
- [Provider integrations](https://github.com/bigcommerce/checkout-js/blob/master/packages/adyen-integration/src/adyenv3/AdyenV3PaymentMethod.tsx): `packages/adyen-integration/src/adyenv3/AdyenV3PaymentMethod.tsx`

### Checkout platform

- [Checkout context](https://github.com/bigcommerce/checkout-js/blob/master/packages/contexts/src/checkout/useCheckout.tsx): `packages/contexts/src/checkout/useCheckout.tsx`
- [Extension service](https://github.com/bigcommerce/checkout-js/blob/master/packages/checkout-extension/src/ExtensionService.ts): `packages/checkout-extension/src/ExtensionService.ts`
- [Extension handlers](https://github.com/bigcommerce/checkout-js/blob/master/packages/checkout-extension/src/handler/commandHandlers/index.ts): `packages/checkout-extension/src/handler/commandHandlers/index.ts`
- [Extension queries](https://github.com/bigcommerce/checkout-js/blob/master/packages/checkout-extension/src/handler/queryHandlers/QueryHandler.ts): `packages/checkout-extension/src/handler/queryHandlers/QueryHandler.ts`
- [Extension regions](https://github.com/bigcommerce/checkout-js/blob/master/packages/checkout-extension/src/ExtensionRegionContainer.ts): `packages/checkout-extension/src/ExtensionRegionContainer.ts`

### Other components

- **Shopper**

## Connections

- Shopper → Checkout app: uses (evidence: `README.md`)
- Checkout app → Shopper: checkout UI (evidence: `README.md`)
- Company address search → Checkout context: gets service (evidence: `packages/core/src/app/address/useCompanyAddressSearch.ts`)
- Hosted card fields → Payment form API: uses form
- Hosted card fields → Extension handlers: renders validation (evidence: `packages/hosted-credit-card-integration/src/hooks/useHostedCreditCard.tsx`)
- Extension service → Extension handlers: registers commands (evidence: `packages/checkout-extension/src/ExtensionService.ts`)
- Extension service → Extension queries: registers queries (evidence: `packages/checkout-extension/src/ExtensionService.ts`)
- Extension service → Extension regions: renders region
