Catalog and search
How product data is owned by the Product Catalog System and projected into Search for customer discovery.
CatalogCatalogDomainv1.0.0The Catalog domain owns everything about products — how they are created, maintained and made discoverable across Acme I...Ownerproduct-platformMapView docs owns the product information that customers browse and buy. It is split into two systems with different consistency needs.
System context map
Product Catalog System
Product Catalog SystemProduct Catalog SystemSystemv1.0.0Internal system that is the source of truth for product data. Owns the product database and publishes product change eve...Ownerproduct-platformMapView docs is the source of truth. Product APIProduct APIServicev1.0.0
The public-facing API for the product catalog. Handles commands to create, update and delete products, serves product re...Subscribescreate-product, update-product +2APIsOpenAPIOwnerproduct-platformMapRepoView docs handles product commands and reads from Product DatabaseProduct DatabaseContainerv1.0.0
PostgreSQL database that is the system of record for all product data.MapView docs. Product changes are captured through an outbox and published by Product Search PublisherProduct Search PublisherServicev1.0.0
Reads product changes from the product database (outbox) and reliably publishes product-created, product-updated and pro...Publishesproduct-created, product-updated +1Ownerproduct-platformMapRepoView docs.
Key contracts:
- Create ProductCreate ProductCommandv1.0.0Command to add a new product to the catalog. Ownerproduct-platformSchemaMapView docs
- Update ProductUpdate ProductCommandv1.0.0Command to update an existing product in the catalog. Ownerproduct-platformSchemaMapView docs
- Delete ProductDelete ProductCommandv1.0.0Command to remove a product from the catalog. Ownerproduct-platformSchemaMapView docs
- Get ProductGet ProductQueryv1.0.0Query to fetch a single product by its identifier. Ownerproduct-platformSchemaMapView docs
- Product CreatedProduct CreatedEventv1.0.0Published when a new product has been added to the catalog. Ownerproduct-platformSchemaMapView docs
- Product UpdatedProduct UpdatedEventv1.0.0Published when an existing product's data has changed. Ownerproduct-platformSchemaMapView docs
- Product DeletedProduct DeletedEventv1.0.0Published when a product has been removed from the catalog. Ownerproduct-platformSchemaMapView docs
Search System
Search SystemSearch SystemSystemv1.0.0Internal system that keeps product data searchable. Consumes product change events from the Product Catalog System, main...Ownersearch-platformMapView docs serves product discovery through Search APISearch APIServicev1.0.0Public-facing API that serves fast, relevant product search to the rest of the business, reading from the search index.
Subscribessearch-productsAPIsOpenAPIOwnersearch-platformMapRepoView docs and Search ProductsSearch ProductsQueryv1.0.0Query to search the catalog for products matching a term, with optional filters and pagination.
Ownersearch-platformSchemaMapView docs. It maintains Search IndexSearch IndexContainerv1.0.0
The denormalised, search-optimised index of products that powers product search.MapView docs from product events.
The Search System should be treated as eventually consistent with the Product Catalog System. If a merchandiser updates a product, the product database is immediately authoritative; search visibility follows after indexing.
Decision context
The product catalog has several architecture decisions documented directly on the system:
- ADR-001: Publish product events via a transactional outboxADR-001: Publish product events via a transactional outboxDecision Recordv1.0.0Product change events are written to an outbox table in the same transaction as the change, then relayed to the broker, ...Ownerproduct-platformView docs
- ADR-002: Use PostgreSQL as the product system of recordADR-002: Use PostgreSQL as the product system of recordDecision Recordv1.0.0Product data is stored in a single PostgreSQL database that acts as the authoritative system of record, with derived sto...Ownerproduct-platformView docs
- ADR-003: Offload long-running catalog work to a dedicated workerADR-003: Offload long-running catalog work to a dedicated workerDecision Recordv1.0.0Slow and asynchronous catalog tasks (enrichment, image processing, bulk imports) run in a separate Product Worker so the...Ownerproduct-platformView docs
These decisions explain why product events are published asynchronously and why Postgres remains the system of record.