An event is a news report from a system: something has happened, and other services may want to hear about it. An OrderPlaced event records a completed fact; it does not tell the shipping service what to do. Once recorded, the event is immutable—history is not rewritten. section 7.2.2 section 7.5.1
A command asks a specific service to perform an action, such as ChargeCreditCard. An event announces a past fact, such as CreditCardCharged, without requiring the sender to know who will react. Choose a command when a specific outcome from a specific service matters; choose an event when independent services should be free to react. section 7.2.2
Figure 7.4 Commands are directed instructions (Coupled). Events are broadcast facts (Decoupled).

Compare a directed command with a broadcast event. section 7.2.2
Events help services work at different times. A producer publishes an event to a broker, then moves on; consumers process it when ready. That breathing room also creates a gap between publication and processing, so the system must accommodate eventual consistency rather than expect every service to update immediately. section 7.1.1 section 7.9
A typical brokered event follows four handoffs:
- Publication: the producer creates the event and hands it to the broker. section 7.4.3
- Persistence: the broker stores the event so it can wait for a consumer. section 7.4.3
- Consumption: a consumer receives the event and performs its work. section 7.4.3
- Acknowledgment: after successful processing, the consumer tells the broker the work is complete. section 7.4.3
Retries are a safety net with a catch. If a shipping service prints a label but crashes before acknowledging the event, the broker can send it again—and a second label may be printed. Idempotent consumers help make repeated processing safe. Events also make strict transactions harder: an email already sent cannot simply be rolled back. section 7.4.3 section 7.2.2
Keep the event itself a simple data carrier:
- Name it in the past tense, and include only the data needed to describe what happened. section 7.5.1 section 7.9
- Include a schema version so consumers can handle payload changes safely, and use simple data types for serialization. section 7.5.1
- Keep business logic out of the event. The broker and dispatcher handle transport; consumers handle their own reactions. section 7.5 section 7.5.1
Listing 7.1 Event Code
namespace Clarity.Shared.Events
{
public record OrderPlaced : IEvent #A
{
// UniqueID of specific event occurrence (used by Idempotent Consumers)
public Guid EventId { get; init; } = Guid.NewGuid();
// Schema version to manage contract evolution over time
public string SchemaVersion { get; init; } = "1.0";
// The "Thread" ID that tracks the request across services
public Guid CorrelationId { get; init; }
public Guid OrderId { get; init; }
public Guid UserId { get; init; }
public decimal TotalAmount { get; init; }
public DateTime OccurredOn { get; init; } = DateTime.UtcNow; #B
}
}Inspect an OrderPlaced record with an event ID, schema version, correlation ID, order data, and occurrence time. section 7.5.1
A comment waits for analysis
A CommentPosted event carries a correlation ID and comment text. A producer puts it on a channel and immediately reports that the comment was received; a background consumer waits to simulate AI analysis, then prints the result. The event lets the producer finish without waiting for that analysis. section 7.7.1




