# medusajs/b2b-starter architecture

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

- Interactive diagram: https://gitdiagram.com/medusajs/b2b-starter
- Repository: https://github.com/medusajs/b2b-starter

## Overview

Medusa B2B Starter combines a Next.js commerce storefront with a Medusa backend. A customer browses products, manages a cart, and checks out; business accounts add company employees, spending controls, order approvals, and quote negotiation. Merchants administer companies, approvals, and quotes through the Medusa admin. The backend exposes store/admin APIs and uses workflows and domain modules for B2B operations. README capabilities also include bulk cart updates, promotions, free-shipping progress, and order editing. Several storefront and API relationships are inferred from product documentation; only evidenced call paths are solid.

Main entry points: [`apps/backend/src/admin/routes/companies/page.tsx`](https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/admin/routes/companies/page.tsx) (Merchant dashboard), [`apps/backend/src/api/store/free-shipping/prices/route.ts`](https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/api/store/free-shipping/prices/route.ts) (Commerce endpoints), [`apps/backend/src/workflows/company/workflows`](https://github.com/medusajs/b2b-starter/tree/main/apps/backend/src/workflows/company/workflows) (Company workflows), [`apps/storefront/src/modules/cart/templates/index.tsx`](https://github.com/medusajs/b2b-starter/blob/main/apps/storefront/src/modules/cart/templates/index.tsx) (Cart)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storefront["Customer storefront"]
  node_catalog["Product catalog<br/>[page.tsx]"]
  node_cart_ui["Cart<br/>[index.tsx]"]
  node_checkout_ui["Checkout<br/>[page.tsx]"]
  node_account_ui["Business account<br/>[page.tsx]"]
  node_quote_ui["Quote portal<br/>[page.tsx]"]
  node_storefront_data["Storefront data access"]
end

subgraph group_backend_api["Backend APIs"]
  node_company_api["Company endpoints<br/>[route.ts]"]
  node_approval_api["Approval endpoints<br/>[route.ts]"]
  node_quote_api["Quote endpoints<br/>[route.ts]"]
  node_commerce_api["Commerce endpoints<br/>[route.ts]"]
  node_admin_company_api["Admin company API<br/>[route.ts]"]
  node_admin_approval_api["Admin approval API<br/>[route.ts]"]
  node_admin_quote_api["Admin quote API<br/>[route.ts]"]
end

subgraph group_b2b_domain["B2B domain"]
  node_company_workflows["Company workflows"]
  node_employee_workflows["Employee workflows"]
  node_approval_workflows["Approval workflows"]
  node_quote_workflows["Quote workflows"]
  node_company_module["Company domain<br/>[service.ts]"]
  node_approval_module["Approval domain<br/>[service.ts]"]
  node_quote_module["Quote domain<br/>[service.ts]"]
end

subgraph group_commerce["Commerce operations"]
  node_commerce_workflows["Order and cart operations"]
  node_commerce_store[("Commerce data store")]
end

subgraph group_admin["Merchant admin"]
  node_admin_ui["Merchant dashboard<br/>[page.tsx]"]
end

node_customer(("Business customer"))
node_merchant(("Merchant"))

node_customer -->|"browses"| node_catalog
node_customer -->|"shops with"| node_cart_ui
node_cart_ui -->|"proceeds to"| node_checkout_ui
node_customer -->|"manages account"| node_account_ui
node_customer -->|"negotiates quotes"| node_quote_ui
node_merchant -->|"administers"| node_admin_ui
node_account_ui -.->|"uses"| node_company_api
node_quote_ui -.->|"uses"| node_quote_api
node_cart_ui -.->|"requests shipping prices"| node_commerce_api
node_company_api -->|"creates companies"| node_company_workflows
node_company_workflows -->|"creates default settings"| node_approval_workflows
node_company_workflows -->|"links company records"| node_company_module
node_company_api -.->|"queries company data"| node_company_module
node_approval_api -->|"queries approval data"| node_commerce_store
node_quote_api -->|"creates quote request"| node_quote_workflows
node_quote_workflows -.->|"manages quote records"| node_quote_module
node_admin_company_api -->|"creates companies"| node_company_workflows
node_admin_approval_api -->|"queries approval data"| node_commerce_store
node_admin_ui -.->|"administers companies"| node_admin_company_api
node_admin_ui -.->|"manages approvals"| node_admin_approval_api
node_admin_ui -.->|"manages quotes"| node_admin_quote_api
node_commerce_api -->|"reads cart"| node_commerce_store
node_commerce_api -->|"lists shipping options"| node_commerce_workflows
node_employee_workflows -.->|"manages employee relations"| node_company_module
node_approval_workflows -.->|"manages approval records"| node_approval_module
node_storefront_data -.->|"requests commerce data"| node_commerce_api

click node_catalog "https://github.com/medusajs/b2b-starter/blob/main/apps/storefront/src/app/%5BcountryCode%5D/(main)/products/%5Bhandle%5D/page.tsx"
click node_cart_ui "https://github.com/medusajs/b2b-starter/blob/main/apps/storefront/src/modules/cart/templates/index.tsx"
click node_checkout_ui "https://github.com/medusajs/b2b-starter/blob/main/apps/storefront/src/app/%5BcountryCode%5D/(checkout)/checkout/page.tsx"
click node_account_ui "https://github.com/medusajs/b2b-starter/blob/main/apps/storefront/src/app/%5BcountryCode%5D/(main)/account/%40dashboard/company/page.tsx"
click node_quote_ui "https://github.com/medusajs/b2b-starter/blob/main/apps/storefront/src/app/%5BcountryCode%5D/(main)/account/%40dashboard/quotes/page.tsx"
click node_company_api "https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/api/store/companies/route.ts"
click node_approval_api "https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/api/store/approvals/route.ts"
click node_quote_api "https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/api/store/quotes/route.ts"
click node_commerce_api "https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/api/store/free-shipping/prices/route.ts"
click node_company_workflows "https://github.com/medusajs/b2b-starter/tree/main/apps/backend/src/workflows/company/workflows"
click node_employee_workflows "https://github.com/medusajs/b2b-starter/tree/main/apps/backend/src/workflows/employee/workflows"
click node_approval_workflows "https://github.com/medusajs/b2b-starter/tree/main/apps/backend/src/workflows/approval/workflows"
click node_quote_workflows "https://github.com/medusajs/b2b-starter/tree/main/apps/backend/src/workflows/quote/workflows"
click node_company_module "https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/modules/company/service.ts"
click node_approval_module "https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/modules/approval/service.ts"
click node_quote_module "https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/modules/quote/service.ts"
click node_storefront_data "https://github.com/medusajs/b2b-starter/tree/main/apps/storefront/src/lib/data"
click node_admin_ui "https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/admin/routes/companies/page.tsx"
click node_admin_company_api "https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/api/admin/companies/route.ts"
click node_admin_approval_api "https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/api/admin/approvals/route.ts"
click node_admin_quote_api "https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/api/admin/quotes/route.ts"
click node_commerce_workflows "https://github.com/medusajs/b2b-starter/tree/main/apps/backend/src/workflows"

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_catalog,node_cart_ui,node_checkout_ui,node_account_ui,node_quote_ui,node_storefront_data toneBlue
class node_company_api,node_approval_api,node_quote_api,node_commerce_api,node_admin_company_api,node_admin_approval_api,node_admin_quote_api toneAmber
class node_company_workflows,node_employee_workflows,node_approval_workflows,node_quote_workflows,node_company_module,node_approval_module,node_quote_module toneMint
class node_commerce_workflows,node_commerce_store toneRose
class node_admin_ui,node_customer,node_merchant toneIndigo
```

## Components

### Customer storefront

- [Product catalog](https://github.com/medusajs/b2b-starter/blob/main/apps/storefront/src/app/%5BcountryCode%5D/(main)/products/%5Bhandle%5D/page.tsx): `apps/storefront/src/app/[countryCode]/(main)/products/[handle]/page.tsx`
- [Cart](https://github.com/medusajs/b2b-starter/blob/main/apps/storefront/src/modules/cart/templates/index.tsx): `apps/storefront/src/modules/cart/templates/index.tsx`
- [Checkout](https://github.com/medusajs/b2b-starter/blob/main/apps/storefront/src/app/%5BcountryCode%5D/(checkout)/checkout/page.tsx): `apps/storefront/src/app/[countryCode]/(checkout)/checkout/page.tsx`
- [Business account](https://github.com/medusajs/b2b-starter/blob/main/apps/storefront/src/app/%5BcountryCode%5D/(main)/account/%40dashboard/company/page.tsx): `apps/storefront/src/app/[countryCode]/(main)/account/@dashboard/company/page.tsx`
- [Quote portal](https://github.com/medusajs/b2b-starter/blob/main/apps/storefront/src/app/%5BcountryCode%5D/(main)/account/%40dashboard/quotes/page.tsx): `apps/storefront/src/app/[countryCode]/(main)/account/@dashboard/quotes/page.tsx`
- [Storefront data access](https://github.com/medusajs/b2b-starter/tree/main/apps/storefront/src/lib/data): `apps/storefront/src/lib/data`

### Backend APIs

- [Company endpoints](https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/api/store/companies/route.ts): `apps/backend/src/api/store/companies/route.ts`
- [Approval endpoints](https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/api/store/approvals/route.ts): `apps/backend/src/api/store/approvals/route.ts`
- [Quote endpoints](https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/api/store/quotes/route.ts): `apps/backend/src/api/store/quotes/route.ts`
- [Commerce endpoints](https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/api/store/free-shipping/prices/route.ts): `apps/backend/src/api/store/free-shipping/prices/route.ts`
- [Admin company API](https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/api/admin/companies/route.ts): `apps/backend/src/api/admin/companies/route.ts`
- [Admin approval API](https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/api/admin/approvals/route.ts): `apps/backend/src/api/admin/approvals/route.ts`
- [Admin quote API](https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/api/admin/quotes/route.ts): `apps/backend/src/api/admin/quotes/route.ts`

### B2B domain

- [Company workflows](https://github.com/medusajs/b2b-starter/tree/main/apps/backend/src/workflows/company/workflows): `apps/backend/src/workflows/company/workflows`
- [Employee workflows](https://github.com/medusajs/b2b-starter/tree/main/apps/backend/src/workflows/employee/workflows): `apps/backend/src/workflows/employee/workflows`
- [Approval workflows](https://github.com/medusajs/b2b-starter/tree/main/apps/backend/src/workflows/approval/workflows): `apps/backend/src/workflows/approval/workflows`
- [Quote workflows](https://github.com/medusajs/b2b-starter/tree/main/apps/backend/src/workflows/quote/workflows): `apps/backend/src/workflows/quote/workflows`
- [Company domain](https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/modules/company/service.ts): `apps/backend/src/modules/company/service.ts`
- [Approval domain](https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/modules/approval/service.ts): `apps/backend/src/modules/approval/service.ts`
- [Quote domain](https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/modules/quote/service.ts): `apps/backend/src/modules/quote/service.ts`

### Commerce operations

- [Order and cart operations](https://github.com/medusajs/b2b-starter/tree/main/apps/backend/src/workflows): `apps/backend/src/workflows`
- **Commerce data store**

### Merchant admin

- [Merchant dashboard](https://github.com/medusajs/b2b-starter/blob/main/apps/backend/src/admin/routes/companies/page.tsx): `apps/backend/src/admin/routes/companies/page.tsx`

### Other components

- **Business customer**
- **Merchant**

## Connections

- Business customer → Product catalog: browses
- Business customer → Cart: shops with
- Cart → Checkout: proceeds to
- Business customer → Business account: manages account
- Business customer → Quote portal: negotiates quotes
- Merchant → Merchant dashboard: administers
- Business account → Company endpoints: uses
- Quote portal → Quote endpoints: uses
- Cart → Commerce endpoints: requests shipping prices
- Company endpoints → Company workflows: creates companies (evidence: `apps/backend/src/api/store/companies/route.ts`)
- Company workflows → Approval workflows: creates default settings (evidence: `apps/backend/src/workflows/company/workflows/create-companies.ts`)
- Company workflows → Company domain: links company records (evidence: `apps/backend/src/workflows/company/workflows/create-companies.ts`)
- Company endpoints → Company domain: queries company data
- Approval endpoints → Commerce data store: queries approval data (evidence: `apps/backend/src/api/store/approvals/route.ts`)
- Quote endpoints → Quote workflows: creates quote request (evidence: `apps/backend/src/api/store/quotes/route.ts`)
- Quote workflows → Quote domain: manages quote records
- Admin company API → Company workflows: creates companies (evidence: `apps/backend/src/api/admin/companies/route.ts`)
- Admin approval API → Commerce data store: queries approval data (evidence: `apps/backend/src/api/admin/approvals/route.ts`)
- Merchant dashboard → Admin company API: administers companies
- Merchant dashboard → Admin approval API: manages approvals
- Merchant dashboard → Admin quote API: manages quotes
- Commerce endpoints → Commerce data store: reads cart (evidence: `apps/backend/src/api/store/free-shipping/prices/route.ts`)
- Commerce endpoints → Order and cart operations: lists shipping options (evidence: `apps/backend/src/api/store/free-shipping/prices/route.ts`)
- Employee workflows → Company domain: manages employee relations
- Approval workflows → Approval domain: manages approval records
- Storefront data access → Commerce endpoints: requests commerce data
