Overview

Product Marketplace owns the active product catalog workflows in api-v1: product models and variants, object categories, parameter values, price groups, vendors, image publishing, and the product scraping platform.

The current implementation lives in apps/api-v1/src/modules/product-marketplace. It follows the api-v1 modular monolith and ports/adapters conventions with Airtable as the persistence adapter.

Implementation Status

Status: Implemented in api-v1

The future api-v2 product-marketplace module is the long-term Prisma/Postgres target, but this domain page documents the active api-v1 implementation first.

Primary Code References

• Module root: apps/api-v1/src/modules/product-marketplace
• Composition root: apps/api-v1/src/modules/product-marketplace/composition/product-marketplace.composition.ts
• REST adapters: apps/api-v1/src/modules/product-marketplace/adapters/inbound/rest
• Generated OpenAPI: apps/api-v1/openapi/openapi.json

Documentation Links

• api-v1 service: /docs/services/api-v1
• Party Directory shared service: /docs/services/party-directory
• Shared Scraping service: /docs/services/shared-scraping
• Product ingestion system: /docs/systems/product-ingestion
• Backend platform: /docs/systems/backend-platform
• Ubiquitous language: /docs/domains/product-marketplace/language
• ADRs: docs/adr/README.md
• Migration overview source: eventcatalog/domains/product-marketplace/migration.mdx

Flows

• Create Product From URL
• Refresh and Reload Product Scrape
• Parameter Graph Persistence

Graph mutations are no longer a product-marketplace flow: see Object Class Graph Mutations in BIM Ontology.

Parameter ownership

The canonical parameter dictionary is owned by BIM Ontology, not by this domain. ParameterKey, ParameterValue, ParameterValueGroup, ParameterGroup, ParameterSpec, and ParameterControl are defined once there. Product Marketplace assigns an object class to a product and uses the parameters that come with that class; it does not define its own parameter concepts.

The live code is apps/api-v1/src/modules/bim-ontology/core/domain/. The former product-marketplace parameter-key, parameter-value, parameter-value-group, and category-parameter directories no longer exist. Where this domain still needs to read a canonical value it does so by explicit cross-module import — CatalogReadUseCases.ts imports ParameterValue and ParameterValueGroup from @modules/bim-ontology and serves them over the internal catalog-read routes.

Retired product-marketplace page	Where the concept lives now
ParameterKey	ParameterKey — same concept, one record per handle, lifecycle draft → active → approved → archived
CategoryParameter	ClassParameter — the assignment of one parameter key to one ObjectClass
CategoryParameterAllowedValue	The allowed-value children of ClassParameter, documented on that page
ParameterValue	ParameterValue — one canonical value a key can take, with its QuantityValue parts
ParameterValueGroup	ParameterValueGroup — a reusable ordered set of values applied as a template

BIM Ontology also owns two concepts this domain never had a page for: ParameterGroup, the authoring grouping, and RevitParameterProjection, the Revit-facing expression of an approved key.

ObjectCategory is likewise the old name for ObjectClass; scraping documentation in this domain that still says “object category” is describing that concept. The class tree and its mutation endpoints belong to bim-ontology — see Object Class Graph Mutations.

Scraping either maps a scraped attribute onto an approved key or creates a new key in active, so product data is visible on the storefront while still flagged as needing steward mapping — that is the whole reason the active state exists. See Why active exists.

The junctions that genuinely belong to this domain stay here:

• L2: ModelParameter (+ allowed-value children; MTO source of truth)
• L3: VariantParameter (renamed from legacy parameter_assignments)

Scrape persistence details: Parameter Graph Persistence.

Open Questions

• Which product-marketplace concepts move first into api-v2?
• Which legacy REST stubs should remain visible in OpenAPI versus be removed?
• Which Airtable tables should become the first Azimutt layout when persistence-model documentation starts?