generated: '2026-08-07'
method: derived
source: graphql/black-buffalo-storefront.graphql
description: >-
  Entity-relationship graph derived from the GraphQL SDL anonymously introspected off
  Black Buffalo's own host. Every entity and every relationship below was read from a
  field declaration in the SDL — nothing is inferred beyond the type system. Identifiers
  are Shopify global IDs unless noted.
id_scheme:
  format: 'gid://shopify/{Type}/{id}'
  encoding: opaque ID scalar (globally unique, resolvable via the node/nodes queries)
  observed_in_tool_docs: ['gid://shopify/Checkout/abc123', 'gid://shopify/Product/...', 'gid://shopify/ProductVariant/...']
  handles: >-
    Product, Collection, Page, Blog, Article and Metaobject also carry a human-readable
    `handle` used in storefront URLs and in the *ByHandle queries.
entities:
- name: Shop
  root: true
  key_fields: [id, name, description, primaryDomain, paymentSettings, shipsToCountries, moneyFormat, brand]
  policies: [privacyPolicy, refundPolicy, shippingPolicy, termsOfService, subscriptionPolicy]
  observed_values: {name: Black Buffalo, primaryDomain: 'https://blackbuffalo.com', currency: USD, shipsToCountries: [US]}
- name: Product
  key_fields: [id, handle, title, description, productType, vendor, tags, availableForSale, priceRange, totalInventory, requiresSellingPlan, publishedAt]
  domain: catalog
- name: ProductVariant
  key_fields: [id, sku, barcode, title, price, compareAtPrice, availableForSale, quantityAvailable, selectedOptions, weight, weightUnit, requiresShipping]
  domain: catalog
- name: ProductOption
  key_fields: [id, name, optionValues]
  domain: catalog
  note: 'Black Buffalo''s option axes are flavor (Wintergreen, Mint, Straight, Blood Orange, Peach), format (pouch vs long cut) and pack size (single can vs 5-can roll).'
- name: SellingPlanGroup
  key_fields: [appName, name, options, sellingPlans]
  domain: subscriptions
  note: Backs the "subscribe and save" recurring-order offer named in /agents.md.
- name: Collection
  key_fields: [id, handle, title, description, image, updatedAt]
  domain: catalog
  known_handles: [nicotine-pouches, long-cut, zero, all, shop]
- name: Cart
  key_fields: [id, checkoutUrl, totalQuantity, cost, note, attributes, createdAt, updatedAt]
  domain: commerce
- name: CartLine
  key_fields: [id, quantity, cost, merchandise, sellingPlanAllocation, discountAllocations]
  domain: commerce
- name: CartBuyerIdentity
  key_fields: [email, phone, countryCode, customer, deliveryAddressPreferences]
  domain: commerce
- name: CartDeliveryGroup
  key_fields: [id, deliveryAddress, deliveryOptions, selectedDeliveryOption]
  domain: fulfillment
- name: Checkout
  key_fields: [id, line_items, totals, discounts, taxes, payment.instruments, status]
  domain: commerce
  surface: UCP MCP only
  note: >-
    A UCP-level entity with NO type in the Storefront GraphQL schema. Its shape is read
    from the create_checkout / update_checkout / complete_checkout tool inputSchemas in
    mcp/black-buffalo-ucp-mcp-tools.json, not from the SDL.
- name: Order
  key_fields: [id]
  domain: commerce
  surface: UCP MCP only
  note: >-
    get_order returns order detail, but the anonymous Storefront GraphQL schema has no
    order query — orders otherwise sit behind the Customer Account API
    (customer-account-api:full).
- name: Customer
  key_fields: [id, email, phone, firstName, lastName, displayName, numberOfOrders, tags, defaultAddress]
  domain: identity
- name: MailingAddress
  key_fields: [id, address1, address2, city, provinceCode, countryCodeV2, zip, phone, firstName, lastName, company]
  domain: identity
- name: Article
  key_fields: [id, handle, title, content, excerpt, publishedAt, authorV2, image, tags]
  domain: content
  note: Backs the /blogs/stories and /blogs/cool-stuff archives.
- name: Blog
  key_fields: [id, handle, title, articles]
  domain: content
- name: Page
  key_fields: [id, handle, title, body, onlineStoreUrl]
  domain: content
  note: 'Carries /pages/faq, /pages/our-story, /pages/rewards and the ~60 "{retailer}-near-me" retail-availability pages.'
- name: Menu
  key_fields: [id, handle, title, items]
  domain: content
- name: Metaobject
  key_fields: [id, handle, type, fields, updatedAt]
  domain: content
- name: Metafield
  key_fields: [id, namespace, key, value, type, reference]
  domain: extension
- name: Location
  key_fields: [id, name, address]
  domain: fulfillment
relationships:
- {from: Shop, to: Collection, type: has_many, via: collections}
- {from: Shop, to: Product, type: has_many, via: products}
- {from: Shop, to: Blog, type: has_many, via: blogs}
- {from: Shop, to: Page, type: has_many, via: pages}
- {from: Shop, to: Location, type: has_many, via: locations}
- {from: Shop, to: Menu, type: has_many, via: menu}
- {from: Collection, to: Product, type: has_many, via: products}
- {from: Product, to: ProductVariant, type: has_many, via: variants}
- {from: Product, to: ProductOption, type: has_many, via: options}
- {from: Product, to: SellingPlanGroup, type: has_many, via: sellingPlanGroups}
- {from: Product, to: Collection, type: has_many, via: collections}
- {from: Product, to: Metafield, type: has_many, via: metafields}
- {from: ProductVariant, to: Product, type: belongs_to, via: product}
- {from: ProductVariant, to: SellingPlanAllocation, type: has_many, via: sellingPlanAllocations}
- {from: Cart, to: CartLine, type: has_many, via: lines}
- {from: Cart, to: CartBuyerIdentity, type: has_one, via: buyerIdentity}
- {from: Cart, to: CartDeliveryGroup, type: has_many, via: deliveryGroups}
- {from: Cart, to: Metafield, type: has_many, via: metafields}
- {from: CartLine, to: ProductVariant, type: has_one, via: merchandise}
- {from: CartLine, to: SellingPlanAllocation, type: has_one, via: sellingPlanAllocation}
- {from: CartBuyerIdentity, to: Customer, type: has_one, via: customer}
- {from: CartBuyerIdentity, to: MailingAddress, type: has_many, via: deliveryAddressPreferences}
- {from: CartDeliveryGroup, to: MailingAddress, type: has_one, via: deliveryAddress}
- {from: CartDeliveryGroup, to: CartLine, type: has_many, via: cartLines}
- {from: Customer, to: MailingAddress, type: has_many, via: addresses}
- {from: Customer, to: MailingAddress, type: has_one, via: defaultAddress}
- {from: Blog, to: Article, type: has_many, via: articles}
- {from: Article, to: Blog, type: belongs_to, via: blog}
- {from: Checkout, to: Cart, type: belongs_to, via: 'UCP server-side association (not in SDL)'}
- {from: Order, to: Checkout, type: belongs_to, via: 'complete_checkout returns the order id (not in SDL)'}
surface_divergence:
  note: >-
    Checkout and Order exist only on the UCP MCP surface. Everything else is grounded in
    the SDL. See mcp/black-buffalo-tool-crosswalk.yml for the full divergence record.
counts:
  entities_documented: 20
  relationships_documented: 28
  sdl_object_types: 262
  sdl_connection_types: 28