liveBook · Manning

Event

As explained in Grokking Software Architecture

An immutable representation of something that has happened and may be communicated to downstream consumers.

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

How Grokking Software Architecture covers it

How deep it goes
Explains event design and broker lifecycle with retry risks, while deferring distributed transactions and idempotency in depth.
Examples
Uses an OrderPlaced record, a shipping-label retry, and a CommentPosted pipeline with simulated AI analysis.
What you can do after
Evaluate and understand when to use events, what data to include, and why consumers must account for retries.
How it connects
Connects events to commands, message brokers, eventual consistency, acknowledgments, and idempotency.

Also explained in

Compare how 5 books explain event →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Grokking Software Architecture. The section links point to the parts of the book it draws on.