Skip to content

Product Management Use Cases

This guide walks through common developer scenarios for Product Management. Each section introduces a problem and explains how the platform addresses it.

Creating a Content Lake-backed Book

A developer needs to create a new book product where chapters are sourced from Content Lake documents rather than uploaded as a pre-existing file.

Start by creating a product shell with core metadata: title, authors, description, language, and product type (Book). The product begins in DRAFT state with no content. Next, attach Content Lake documents as chapters. Each attachment specifies a document ID, a chapter order, and a version specifier — either version=latest to track the latest Content Lake version, or version=<id> to pin to a specific version.

The product-level concurrent flag controls the default for new attachments. If concurrent is true, attachments default to version=latest. If false, every attachment requires an explicit version ID.

Cover images (front and back) are uploaded as binary assets — these are the only files stored for Content Lake-backed products. Everything else is a reference or is generated dynamically.

When a client requests a format (PDF, ePub, InDesign), the table of contents is generated from heading structure, the index from entity and keyword data, and the imprint from product metadata. None of these assets are persisted.

The product does not "contain" content — it holds references to Content Lake documents. If a document is deleted, the product reference becomes broken. This is by design: there is always a single source of truth for content.

Managing a Legacy Product

A developer has a pre-existing video course or ePub file and needs to register it in the product catalogue.

Create the product with the same metadata fields, but set the product model to legacy and upload the distributable asset. The asset is opaque to the platform — it stores the file but does not decompose it into chapters or perform content analysis.

Legacy and Content Lake-backed products share the same lifecycle, pricing, search, and event systems. The difference is only in how content is sourced. A product is one model or the other at creation time and cannot be changed later.

ISBNs are assigned per format during the lifecycle, not at creation.

Pinning vs Latest-Tracking Documents

A developer creating a Content Lake-backed book needs to decide the version strategy for each attached document.

Pin to a specific version when content must be stable:

  • The product will be distributed through retail channels requiring a static artifact
  • The chapter has been through editorial review
  • Reproducibility matters — the same request should always produce identical output

Track latest when content freshness matters more:

  • The product is served through a subscription platform
  • The chapter covers a rapidly evolving topic
  • The product is an internal reference or dynamic experience

A single product can mix both strategies. A common pattern is pinning most chapters while letting rapidly-evolving chapters track latest.

When a pinned document's source has been updated, re-pin the attachment by updating the version specifier. This emits a packt.products.content.v1.updated event. Re-pinning is always a deliberate action.

Searching and Discovering Products

A developer needs to build a search feature for a storefront, product discovery API, or internal editor tool.

Product search uses the same hybrid architecture as the Content Lake search pipeline. Products are indexed at the product level with their title, description, authors, tags, and an embedding vector.

Hybrid mode (default) combines BM25 full-text matching with vector similarity. Use keyword mode for known-item retrieval (exact title, ISBN, author name). Use vector mode for recommendation-style queries.

Tag filtering is the most important performance lever. Tag-filtered queries return in ~10–100ms. Unfiltered hybrid search runs in 1–5 seconds. Always combine search with tag filters when scope is known.

Pagination follows the same session-based model as Content Lake search with a search_id for subsequent pages.

Overlaying a Custom Taxonomy

A developer building a storefront needs to categorise products into an application-specific taxonomy without modifying the product catalogue.

Product embeddings are exposed via the API. These vectors encode the semantic content of each product and can be used for classification, clustering, and nearest-neighbour operations outside the platform.

Practical patterns:

  • Batch classification — export embeddings for published products, run through a classifier, store category assignments in the application's database. Re-run when products are created or updated.
  • Real-time classification — fetch a single product's embedding and classify on demand for newly created products.
  • Similarity-based navigation — use vector mode search with a product's embedding to power "more like this" features.

Taxonomy is a client concern. The platform provides the vector space. How you partition it into categories is up to you.

Building a Catalogue for a Storefront

A developer is setting up a new storefront and needs to define which products should appear on the site.

Create a catalogue with rules matching the products the storefront should carry. For a game development storefront:

  • Product type is Book or Video Course
  • Language is en
  • Content Lake documents tagged with game-engine topics
  • Lifecycle state is PUBLISHED

Rules are evaluated continuously. When a new book about Godot is published, it automatically enters the catalogue. Supplement rules with manual picks for products that do not match rules but are editorially relevant.

Catalogue Events Drive Distribution

When a product enters or leaves a catalogue, membership events are emitted (packt.products.catalogue.v1.product_added, packt.products.catalogue.v1.product_removed). The Distribution service subscribes and handles syncing inventory to the channel.

Customising Product Information Per Catalogue

A developer building a Shopify storefront needs titles and descriptions to differ from the base product — promotional suffixes, translations, or audience-tailored descriptions.

Each catalogue entry can override any product attribute using sync, override, or template modes.

Promotional titles:

  • Template: $title — Now 70% Off
  • When the promotion ends, switch back to sync mode

Regional catalogues:

  • Override title: "Microservices mit Go" (German storefront)
  • Static overrides do not track base product changes

Mixing modes: A single entry can use template for title, override for description, and sync for pricing.

Generating Formats On-the-Fly

A developer needs to serve a PDF, ePub, or InDesign file for a Content Lake-backed product.

There is no stored file. Every format request triggers the generation pipeline: Content Lake document retrieval (streaming), asset injection (covers, imprint, ToC, index), format rendering, and response streaming.

For pinned-version products, the output is deterministic. For latest-tracking products, the output reflects the Content Lake state at generation time.

The platform does not cache generated files. For pinned products, downstream CDNs can cache using standard HTTP headers. If a use case requires a persistent file (e.g. uploading to a retail channel), the downstream system should generate, store, and manage its own cache.

Reacting to Content Lake Updates

A Content Lake document attached to several products has been updated. What happens?

Pinned documents: Nothing. The product references the old version. Format generation continues unchanged. To reflect the update, re-pin the attachment manually.

Latest-tracking documents: A packt.products.content.v1.updated event is emitted. Subscribe to this event — not to Content Lake document events directly. The platform translates document events into product-scoped events.

To find all products affected by a document update, query for products referencing that document ID.

Integrating Product Events

A developer needs to react when products are published, pricing changes, or lifecycle transitions occur.

All events are published to the products event bus following the naming convention packt.products.{resource}.v1.{action}. Common consumer patterns:

  • Distribution — product.v1.published, product.v1.withdrawn, catalogue.v1.product_added/removed
  • Search indexing — product.v1.created/updated/deleted
  • Analytics — all lifecycle and pricing.v1.updated events
  • Cache invalidation — content.v1.updated for product pages

Events provide at-least-once delivery. Consumers must be idempotent.

Note the distinction between product.v1.updated (metadata changes) and content.v1.updated (underlying Content Lake content changes). Subscribe to both if you need to react to any change in a product's effective content or metadata.