Event design standards
How Acme teams name, publish, consume and operate business events across the commerce platform.
Events represent business facts, not instructions. The publishing team owns the meaning of the event and the state transition that produced it.
Naming
Event names should be past tense and business-readable:
- Cart Checked OutCart Checked OutEventv1.0.0Published when a customer has checked out their cart. Ownershopping-platformSchemaMapView docs
- Order CreatedOrder CreatedEventv1.0.0Published when a new order has been created. Ownerordering-platformSchemaMapView docs
- Payment SucceededPayment SucceededEventv1.0.0Published by Stripe when a charge succeeds. Ownerpayments-platformSchemaMapView docs
- Review PublishedReview PublishedEventv1.0.0Published when a submitted review passes moderation and becomes visible on the storefront. Ownerreviews-platformSchemaMapView docs
Avoid names that describe infrastructure actions, implementation classes or subscriber intent.
Publishing
Publish events from the system that owns the state change. For product changes, 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 publishes product events because Product DatabaseProduct DatabaseContainerv1.0.0
PostgreSQL database that is the system of record for all product data.Ownerproduct-platformMapView docs is authoritative. For order lifecycle changes, Order Management SystemOrder Management SystemSystemv1.0.0Internal system that is the source of truth for orders. It creates orders, tracks their lifecycle, and publishes events ...Ownerordering-platformMapView docs publishes order events because Order DatabaseOrder DatabaseContainerv1.0.0PostgreSQL database that is the system of record for orders and their items.Ownerordering-platformMapView docs is authoritative.
Use an outbox or equivalent durable handoff for events that represent committed business state.
Consumption
Consumers must be idempotent. Delivery can be retried, delayed or observed out of order across independent streams. Consumers should store processed event identifiers when duplicate handling would otherwise create side effects.
Event payloads
Payloads should carry enough information for consumers to decide whether they care, but not a full copy of another domain’s private data model. Include stable identifiers, timestamps and business status fields. Keep sensitive customer and payment data out of broad event payloads.
Review this event design against Acme’s event standards. Check that the event name is a past-tense business fact, the
publisher owns the state change, the payload avoids private data models, consumers can process it idempotently, and the
related flow documentation is updated. Return specific recommendations.Review this event design against Acme’s event standards. Check that the event name is a past-tense business fact, the publisher owns the state change, the payload avoids private data models, consumers can process it idempotently, and the related flow documentation is updated. Return specific recommendations.
Flow impact
When an event is added to a critical journey, update the related flow page. Checkout-related event changes should be reflected in 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 or 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.