flow

Parameter Graph Persistence

Persist scraped parameter assignments through the canonical dictionary, taxonomy upsert, and variant_parameters junction writer.

FlowStatus: Implemented in api-v1

Overview

This flow documents how api-v1 scrape persistence aligns with the canonical parameter schema (PARAM-S5/S6). It runs inside bulk product creation and refresh/reload scrape paths — not as a standalone HTTP endpoint.

Parent workflows:

Entities

  • ParameterKey — owned by bim-ontology; scraping either maps onto an approved key or creates one in active
  • ParameterValue — also owned by bim-ontology; product-marketplace reads it through the internal catalog-read routes
  • VariantParameter — owned by product-marketplace

Ports

  • ForCreatingScrapedParameterGraph — orchestrates taxonomy upsert + junction writes
  • ForReadingCanonicalParameterDictionary — loads dictionary snapshot
  • ForStoringPendingParameterLinks — ephemeral pending-link store
  • ForLinkingVariantParameters — PM mirror lookups and variant_parameters ensure-link

Code References

  • apps/api-v1/src/modules/product-marketplace/adapters/outbound/persistence/airtable/AirtableScrapedParameterGraphAdapter.ts
  • apps/api-v1/src/modules/product-marketplace/adapters/outbound/persistence/airtable/CanonicalParameterDictionaryIndex.ts
  • apps/api-v1/src/modules/product-marketplace/adapters/outbound/persistence/airtable/AirtableVariantParameterLinkingAdapter.ts
  • apps/api-v1/src/modules/product-marketplace/adapters/outbound/scraping/persistence/airtable/bulkProductCreation.service.ts
  • apps/api-v1/src/modules/product-marketplace/core/application/use-cases/ReconcilePendingParameterLinksUseCase.ts
  • apps/api-v1/src/modules/product-marketplace/composition/scrapedParameterGraph.composition.ts

Notes

  • Single junction writer: bulk product creation must not duplicate variant_parameters writes; the graph adapter owns junction creation.
  • Pending-link store: local file at apps/api-v1/.cache/pending-parameter-links.json (ephemeral; durable backing deferred).
  • Stable domain_id: TS mint uses slugified handle; Python Phase-B backfill used legacy key-type inputs — reuse is via dictionary name/handle lookup.
  • Deferred: scraper mapping Airtable tables, live dry-run scrape validation, MTO model_parameters writes (PARAM-S7).

ADRs

Edit this page