Change management
How to safely change contracts, schemas, systems and cross-domain flows in the Acme Inc catalog.
Changes should start with ownership and blast radius. A small service implementation change may not affect the catalog. A schema or flow change usually does.
Contract changes
Before changing a command, event or query:
- Identify the producer and all consumers.
- Check whether the change is backward compatible.
- Update the schema and resource summary.
- Update affected flow pages.
- Coordinate rollout with consumer owners.
High-risk contracts include Cart Checked OutCart Checked OutEventv1.0.0Published when a customer has checked out their cart. Ownershopping-platformSchemaMapView docs, Reserve InventoryReserve InventoryCommandv1.0.0Command to reserve stock for the items in a checked-out cart. Ownerordering-platformSchemaMapView docs, Authorize PaymentAuthorize PaymentCommandv1.0.0Command to authorize payment for the total of a checked-out cart. Ownerordering-platformSchemaMapView docs, Create OrderCreate OrderCommandv1.0.0Command to create a new order from a checked-out cart. Ownerordering-platformSchemaMapView docs, Order CreatedOrder CreatedEventv1.0.0Published when a new order has been created. Ownerordering-platformSchemaMapView docs and Review PublishedReview PublishedEventv1.0.0Published when a submitted review passes moderation and becomes visible on the storefront. Ownerreviews-platformSchemaMapView docs.
System changes
When a system adds a service or data store, update the system page and any domain page that lists that system. If the change alters ownership of data, update the data ownership page too.
Flow changes
For flows such as Place an OrderPlace an OrderFlowv1.0.0The end-to-end journey from a customer checking out their cart to a confirmed order — spanning the Shopping and Ordering...Ownerordering-platformView flowView docs, Checkout SagaCheckout SagaFlowv1.0.0How the Checkout Orchestrator turns a checked-out cart into an order — reserving inventory, authorizing payment and crea...Ownerordering-platformView flowView docs, Product Search IndexingProduct Search IndexingFlowv1.0.0How a change to a product in the catalog reliably flows into the search index — via the outbox, product events and the i...Ownersearch-platformView flowView docs and Review SubmissionReview SubmissionFlowv1.0.0How a customer's product review travels from submission, through moderation, to being published and folded into the prod...Ownerreviews-platformView flowView docs, update the diagram and the narrative together. A diagram without the operating rules is not enough for on-call or onboarding.
Decision records
Use ADRs when a decision changes a long-lived pattern. The Product Catalog System already documents key decisions such as 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 and 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.