--- id: SVC-COM-CAT-catalog title: 'Catalog: shelves, listings, storefront, downloads and catalog files' product_area: commerce module: catalog repository: services-commerce source_module: modules/catalog revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: - DOM-COM-CAT-003 does_not_own: - 'MOD-ACC-PRD controls product status, sale dates and shopper visibility.' - SVC-COM-CAT-merchandise maintains options and variants. - MOD-COM-ORD issues and consumes download grants. - MOD-PFM-ELG defines purchase eligibility. - Platform processes assets and serves files. operations: - operation_id: createProductCategory intent: Prepare a new product shelf with validated configuration. access: console permission: commerce.product-categories.create realises: - CAP-COM-CAT-005 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: listProductCategories intent: Browse the workspace’s product shelves using supported filters. access: console permission: commerce.product-categories.read realises: - CAP-COM-CAT-005 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: getProductCategory intent: Inspect the selected product shelf and its retained details. access: console permission: commerce.product-categories.read realises: - CAP-COM-CAT-005 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: updateProductCategory intent: Save permitted changes to the selected product shelf at its read version. access: console permission: commerce.product-categories.update realises: - CAP-COM-CAT-005 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: deleteProductCategory intent: Remove the selected product shelf when protection and dependencies permit. access: console permission: commerce.product-categories.delete realises: - CAP-COM-CAT-005 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: listCategoryProducts intent: Inspect the ordered products assigned to a shelf. access: console permission: commerce.product-categories.read realises: - CAP-COM-CAT-005 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: replaceCategoryProducts intent: Save the complete ordered product membership of a shelf. access: console permission: commerce.product-categories.update realises: - CAP-COM-CAT-005 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: createProductListing intent: Prepare a new storefront listing with validated configuration. access: console permission: commerce.product-listings.create realises: - CAP-COM-CAT-006 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: listProductListings intent: Browse the workspace’s storefront listings using supported filters. access: console permission: commerce.product-listings.read realises: - CAP-COM-CAT-006 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: getProductListing intent: Inspect the selected storefront listing and its retained details. access: console permission: commerce.product-listings.read realises: - CAP-COM-CAT-006 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: updateProductListing intent: Save permitted changes to the selected storefront listing at its read version. access: console permission: commerce.product-listings.update realises: - CAP-COM-CAT-006 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: deleteProductListing intent: Remove the selected storefront listing when protection and dependencies permit. access: console permission: commerce.product-listings.delete realises: - CAP-COM-CAT-006 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: listStorefrontListings intent: Browse admitted store products with caller-specific prices and availability. access: portal permission: commerce.storefront.read realises: - CAP-COM-CAT-008 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: getStorefrontListing intent: 'Inspect an admitted product presentation, including staff diagnostics where authorized.' access: portal permission: commerce.storefront.read realises: - CAP-COM-CAT-008 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: listPublicStorefrontListings intent: Browse store offerings anonymously with public price display. access: public permission: none (anonymous) realises: - CAP-COM-CAT-008 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: getPublicStorefrontListing intent: 'Open an anonymously accessible product page, including permitted direct links.' access: public permission: none (anonymous) realises: - CAP-COM-CAT-008 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: downloadEntitledFile intent: Obtain a short-lived private link using the caller’s purchased download grant. access: portal permission: commerce.downloads.read realises: - CAP-COM-CAT-009 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: catalog.assetCleanupSweep intent: Claim due released assets and submit cleanup messages. access: internal permission: none (system caller) realises: - CAP-COM-CAT-006 - CAP-COM-CAT-005 - CAP-COM-CAT-003 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: catalog.assetCleanupConsumer intent: Settle queued assets after verifying that owner records no longer retain them. access: internal permission: none (system caller) realises: - CAP-COM-CAT-006 - CAP-COM-CAT-005 - CAP-COM-CAT-003 published_to_submissions: 'not published: this operation has no registered Submissions binding' events: [] jobs: - The scheduled asset sweep runs every fifteen minutes with one reserved invocation. - >- The asset consumer receives work from the cleanup queue, including individual retry and dead-letter handling. integrations: - system: Platform asset pipeline direction: outbound contract: >- The record-asset binding prepares files before save, attaches them inside the save and supplies private delivery links. - system: Platform eligibility (purchase bindings) direction: outbound contract: Display evaluation batches member purchase bindings through Platform eligibility. - system: Entitlements register (orders module) direction: outbound contract: The order register resolves download grants and conditionally consumes limited access. - system: Workspace data export direction: outbound contract: 'Catalog metadata and its dataset declare shelves, listings, gallery images and digital files for export.' consistency: - rule: 'Listing content, gallery, files and shelf assignments commit in one version-checked save.' kind: transactional compensation: The parent transaction rolls back refused writes. - rule: 'Preparation copies files before record writes, while committed attachments determine later cleanup.' kind: eventual compensation: >- Background settlement discards uncommitted copies and retires released files after another reference check. - rule: >- Storefront assembly reads visibility, prices and availability separately, so its output has no single shared snapshot. kind: eventual compensation: A price failure leaves a flagged presentation rather than undoing any saved record. - rule: Limited downloads consume capacity once for the file and request key. kind: transactional compensation: Delivery failure after consumption does not restore the use. evidence: - >- services-commerce at c8b66a98: modules/catalog/aws/api/*.routes.ts, services/**/*.ts, db/*.table.ts, aws/lambda/*.ts, aws/logic/*.ts, aws/resources/*.ts, metadata/*.ts, export/*.ts. - >- react-console at baf6dae3: lib/commerce/catalog/live.ts, components/configuration/resources/product-categories.tsx. controls: [TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-LOG-004, TC-LOG-005, TC-AVL-002, TC-AVL-003, TC-AVL-004, TC-AVL-005, TC-MON-001, TC-MON-002, TC-MON-003, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002] --- # Catalog: shelves, listings, storefront, downloads and catalog files ## What This Service Is For Catalog supplies the shelves and product presentations shoppers browse, delivers entitled digital files and manages the assets those records retain. ## Boundary Accounting owns base products; Merchandise owns goods details and variants. Orders owns download grants, and Platform supplies eligibility and asset services. Catalog reads Accounting products directly while applying workspace-scoped access. ## Operations in Words Staff maintain shelves, ordered product membership and listings. Member and public operations expose admitted storefront pages; staff callers also receive removal explanations. Downloads verify a grant and consume limited capacity before returning a signed link. Internal cleanup entries describe background functions rather than HTTP route declarations. ## Events and Jobs A fifteen-minute schedule queues due asset cleanup. A separate consumer checks references and settles messages individually; exhausted receipts reach a dead-letter queue. Catalog publishes no external event. ## Consistency Guarantees Record and child writes commit atomically, but file preparation and cleanup are eventual. Storefront output combines separate reads. Download delivery can fail after capacity consumption, without restoring that use.