Show me your flowchart and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won’t usually need your flowchart; it’ll be obvious.

—Fred Brooks1

Let’s use Fred Brooks’s reasoning to define the event sourcing pattern and understand how it differs from traditional modeling and persisting of data. Examine Table 7-1 and analyze what you can learn from this data about the system it belongs to.

1 Brooks, F. P. Jr. (1974). The Mythical Man-Month: Essays on Software Engineering. Reading, MA: Addison- Wesley.

Table 7-1. State-based model

It’s evident that the table is used to manage potential customers, or leads, in a tele‐ marketing system. For each lead, you can see their ID, their first and last names, when the record was created and updated, their phone number, and the lead’s current status.

By examining the various statuses, we can also assume the processing cycle each potential customer goes through:

• The sales flow starts with the potential customer in the NEW_LEAD status.

• A sales call can end with the person not being interested in the offer (the lead is CLOSED), scheduling a follow-up call (FOLLOWUP_SET), or accepting the offer (PENDING_PAYMENT).

• If the payment is successful, the lead is CONVERTED into a customer. Conversely, the payment can fail—PAYMENT_FAILED.

That’s quite a lot of information that we can gather just by analyzing a table’s schema and the data stored in it. We can even assume what ubiquitous language was used when modeling the data. But what information is missing from that table?

The table’s data documents the leads’ current states, but it misses the story of how each lead got to their current state. We can’t analyze what was happening during the lifecycles of leads. We don’t know how many calls were made before a lead became CONVERTED. Was a purchase made right away, or was there a lengthy sales journey? Based on the historical data, is it worth trying to contact a person after multiple follow-ups, or is it more efficient to close the lead and move to a more promising prospect? None of that information is there. All we know are the leads’ current states.

These questions reflect business concerns essential for optimizing the sales process. From a business standpoint, it’s crucial to analyze the data and optimize the process based on the experience. One of the ways to fill in the missing information is to use event sourcing.

The event sourcing pattern introduces the dimension of time into the data model. Instead of the schema reflecting the aggregates’ current state, an event sourcing– based system persists events documenting every change in an aggregate’s lifecycle.

Consider the CONVERTED customer on line 12 in Table 7-1. The following listing dem‐ onstrates how the person’s data would be represented in an event-sourced system:

{

"lead-id": 12,

"event-id": 0,

"event-type": "lead-initialized",

"first-name": "Casey",

"last-name": "David",

"phone-number": "555-2951",

"timestamp": "2020-05-20T09:52:55.95Z"

},

{

"lead-id": 12,

"event-id": 1,

"event-type": "contacted",

"timestamp": "2020-05-20T12:32:08.24Z"

},

{

"lead-id": 12,

"event-id": 2,

"event-type": "followup-set",

"followup-on": "2020-05-27T12:00:00.00Z",

"timestamp": "2020-05-20T12:32:08.24Z"

},

{

"lead-id": 12,

"event-id": 3,

"event-type": "contact-details-updated",

"first-name": "Casey",

"last-name": "Davis",

"phone-number": "555-8101",

"timestamp": "2020-05-20T12:32:08.24Z"

},

{

"lead-id": 12,

"event-id": 4,

"event-type": "contacted",

"timestamp": "2020-05-27T12:02:12.51Z"

},

{

"lead-id": 12,

"event-id": 5,

"event-type": "order-submitted",

"payment-deadline": "2020-05-30T12:02:12.51Z",

"timestamp": "2020-05-27T12:02:12.51Z"

},

{

"lead-id": 12,

"event-id": 6,

"event-type": "payment-confirmed",

"status": "converted",

"timestamp": "2020-05-27T12:38:44.12Z"

}

The events in the listing tell the customer’s story. The lead was created in the system (event 0) and was contacted by a sales agent about two hours later (event 1). During the call, it was agreed that the sales agent would call back a week later (event 2), but to a different phone number (event 3). The sales agent also fixed a typo in the last name (event 3). The lead was contacted on the agreed date and time (event 4) and submit‐ ted an order (event 5). The order was to be paid in three days (event 5), but the

payment was received about half an hour later (event 6), and the lead was converted into a new customer.

As we saw earlier, the customer’s state can easily be projected out from these domain events. All we have to do is apply simple transformation logic sequentially to each event:

public class LeadSearchModelProjection

{

public long LeadId { get; private set; }

public HashSet<string> FirstNames { get; private set; }

public HashSet<string> LastNames { get; private set; }

public HashSet<PhoneNumber> PhoneNumbers { get; private set; }

public int Version { get; private set; }

public void Apply(LeadInitialized @event)

{

LeadId = @event.LeadId;

FirstNames = new HashSet<string>(); LastNames = new HashSet<string>(); PhoneNumbers = new HashSet<PhoneNumber>(); FirstNames.Add(@event.FirstName); LastNames.Add(@event.LastName); PhoneNumbers.Add(@event.PhoneNumber); Version = 0;

}

public void Apply(ContactDetailsChanged @event)

{

FirstNames.Add(@event.FirstName); LastNames.Add(@event.LastName); PhoneNumbers.Add(@event.PhoneNumber); Version += 1;

}

public void Apply(Contacted @event)

{

Version += 1;

}

public void Apply(FollowupSet @event)

{

Version += 1;

}

public void Apply(OrderSubmitted @event)

{

Version += 1;

}

public void Apply(PaymentConfirmed @event)

{

Version += 1;

}

}

Iterating an aggregate’s events and feeding them sequentially into the appropriate overrides of the Apply method will produce precisely the state representation mod‐ eled in the table in Table 7-1.

Pay attention to the Version field that is incremented after applying each event. Its value represents the total number of modifications made to the business entity. More‐ over, suppose we apply a subset of events. In that case, we can “travel through time”: we can project the entity’s state at any point of its lifecycle by applying only the rele‐ vant events. For example, if we need the entity’s state in version 5, we can apply only the first five events.

Finally, we are not limited to projecting only a single state representation of the events! Consider the following scenarios.