Products

Maintain the shared catalog of products and services, categories, units of measure, bundles, and pricing rules.

For POS and deal flows that use the catalog, see Sales and POS Client.

Module layout

backend/core-api/src/modules/products/
  graphql/schemas/{product,category,uom,package,rule,similarity,config,index}.ts
  graphql/resolvers/{queries,mutations,customResolvers}/
  db/definitions/{products,categories,uoms,packages,rules,similarities,configs}.ts
  db/models/{Products,Categories,Uoms,Packages,Rules,Similarities,Configs}.ts
  trpc/{product,category,uom,similarity,config,index}.ts
  meta/automations.ts            # AI knowledge provider for automations
  meta/document/productReplacer.ts
  meta/import-export/{import,export}/
  meta/template/                 # category templates
  utils/productRule.ts

Frontend: frontend/core-ui/src/modules/products/ (record table, categories, UoM, packages) with shared product pickers in frontend/libs/ui-modules/src/modules/products/.

Data model

Product (products.ts):

Field	Notes
name, shortName, code	code is unique; the stable external key
categoryId	Links to ProductCategory (tree via parentId, order)
type	product, service, unique, subscription
status	active or deleted (soft delete)
unitPrice, currency	Base price; discounts[] and inventories hold extras
barcodes, variants, barcodeDescription, sameMasks, sameDefault	Barcode/variant matching for POS
uom, subUoms	Unit of measure and convertible sub-units
vendorId, scopeBrandIds, tagIds, mergedIds	Ownership and dedup
customFieldsData, propertiesData	Custom properties
attachment, attachmentMore, videos, pdfAttachment	Media
duration, durationType	For service-type items
similarityId	Links to Similarity groups

Uom (db/definitions/uoms.ts): name, code (unique), isForSubscription, subscriptionConfig (period, rule, specificDay, subsRenewable). ProductRule prices products by conditions; ProductPackage bundles items; Similarity groups mask-matched products; ProductsConfig stores module-wide settings (productsConfigsUpdate).

GraphQL API

Products (graphql/schemas/product.ts)

Operation	Key arguments
productsMain	type, status, categoryId, categoryIds, searchValue, vendorId, brandIds, tag, tagIds, excludeTagIds, tagWithRelated, ids, excludeIds, pipelineId, boardId, segment, segmentIds, propertiesData, groupedSimilarity, similarity, image, brand, branchId, departmentId, minRemainder/maxRemainder, minPrice/maxPrice, discount range args, discountConditions, sortField, sortDirection, cursor params; returns ProductsListResponse
products	same filters with page/perPage; returns a plain [Product]
productsTotalCount	same filters
productDetail	_id
productSimilarities	_id!, groupedSimilarity
productCountByTags	none
productsAdd / productsEdit	name, shortName, categoryId, type, description, barcodes, variants, barcodeDescription, unitPrice, code, propertiesData, attachment, attachmentMore, videos, vendorId, scopeBrandIds, uom, subUoms, currency, duration, durationType, pdfAttachment
productsMerge	productIds, productFields
productsDuplicate / productsRemove	_id! / productIds: [String!]

Categories, units, packages, rules

Operation	Key arguments
productCategories / productCategoriesTotalCount / productCategoryDetail	parentId, searchValue, status, ids / _id
categoriesWithChilds	ids: [String!]!
productCategoriesAdd / productCategoriesEdit / productCategoriesRemove	name, code, parentId, description, meta, attachment, status / _id!
uoms / uomsTotalCount	none
uomsAdd / uomsEdit / uomsRemove	name, code, isForSubscription, subscriptionConfig, timely / uomIds: [String!]
productPackages / productPackageDetail	cursor params / _id!
productPackagesAdd / productPackagesEdit / productPackagesChangeStatus / productPackagesRemove	package fields / _ids, status!
productRules / productRulesWithCount	none
productRulesAdd / productRulesEdit / productRulesRemove	rule fields / _ids
productBulkSimilarity / productBulkSimilarities	_id! / page, perPage, searchValue
productsConfigs / productsConfigsUpdate	none / configsMap: JSON!

Example

query ProductList($categoryId: String) {
  productsMain(categoryId: $categoryId, status: "active", limit: 20) {
    list {
      _id
      name
      code
      unitPrice
      uom
      cursor
    }
    totalCount
    pageInfo { hasNextPage endCursor }
  }
}

mutation AddProduct {
  productsAdd(
    name: "Espresso blend 1kg"
    code: "COF-ESP-1KG"
    type: "product"
    unitPrice: 18.5
    currency: "USD"
    uom: "bag"
    barcodes: ["4006381333931"]
  ) { _id code }
}

How plugins use products

Services do not read the Products collection directly. They call the tRPC router in trpc/product.ts through sendTRPCMessage({ pluginName: 'core', module: 'products', action: ... }). Procedures: find (with automatic categoryId expansion to child categories), findOne, createProduct, updateProduct, updateProducts, removeProducts, count. Example from the POS order route in sales_api:

// backend/plugins/sales_api/src/modules/pos/routes.ts
const products = await sendTRPCMessage({
  subdomain,
  pluginName: 'core',
  module: 'products',
  action: 'find',
  input: { query: { status: { $ne: 'deleted' }, categoryId: { $in: categoryIds } } },
  defaultValue: [],
});

The same pattern appears in the sales pipeline product picker and ecommerce module. Products also show up through meta/document/productReplacer.ts (document templates), meta/automations.ts (AI knowledge provider), and the segment content type core:products.products.

Permissions

Core permission module products (meta/permissions.ts): productsRead (always: true), productsCreate, productsUpdate, productsDelete, productsMerge, productCategoriesManage, productsConfigsManage, uomsManage, productRulesManage, productsImportManage, productsExportManage. Scope is all only; there is no per-owner product scope.