This book is the result of my efforts. Its goal is to democratize domain-driven design; make it easier to understand and more accessible to employ. I believe that the DDD methodology is absolutely invaluable, especially when designing modern software systems. This book will give you just enough tools to start applying domain-driven design in your day-to-day work.

Who Should Read This Book

I believe that knowledge of domain-driven design principles and patterns will be useful for software engineers at all levels: junior, senior, staff, and principal.

Here is a short summary of what you will find in each chapter:

• Chapter 1 establishes the context of a software engineering project: the business domain, its goals, and how the software is intended to support them.

• Chapter 2 introduces the notion of a “ubiquitous language”: domain-driven design’s practice for effective communication and knowledge sharing.

• Chapter 3 discusses how to tackle the complexity of business domains and design the system’s high-level architectural components: bounded contexts.

• Chapter 4 explores the different patterns of organizing the communication and integration between the bounded contexts.

• Chapter 5 starts the discussion of business logic implementation patterns with two patterns addressing the cases of simple business logic.

• Chapter 6 advances from simple to complex business logic and introduces the domain model pattern for tackling its complexity.

• Chapter 7 adds the perspective of time and introduces an even more advanced way to model and implement business logic: the event-sourced domain model.

• Chapter 8 shifts the focus to a higher level and describes three architectural patterns for structuring components.

• Chapter 9 provides the patterns needed to orchestrate the work of the system’s components.

• Chapter 10 ties together the patterns discussed in the earlier chapters into a number of simple rules of thumb that streamline the process of making design decisions.

• Chapter 11 explores software design from the perspective of time and how it is supposed to change and evolve through its lifespan.

• Chapter 12 introduces EventStorming: a low-tech workshop for effectively sharing knowledge, building shared understanding, and designing software.

• Chapter 13 addresses the difficulties you may face when introducing domain-driven design to brownfield projects.

• Chapter 14 discusses the relationship between the microservices architectural style and domain-driven design: where they differ and where they complement each other.

• Chapter 15 explores domain-driven design patterns and tools in the context of the event-driven architecture.

• Chapter 16 shifts the discussion from operational systems to analytical data management systems and discusses the interplay between domain-driven design and the data mesh architecture.

All of these chapters end with a number of exercise questions to reinforce the learning.

All the code samples presented in the book are implemented in the C# language.

This book is here to help you get your job done. In general, if example code is offered with this book, you may use it in your programs and documentation. You do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product’s documentation does require permission.

We appreciate, but generally do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: “Learning Domain-Driven Design by Vlad Khononov (O’Reilly). Copyright 2022 Vladislav Khononov, 978-1-098-10013-1.”

If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact us at permissions@oreilly.com.

O’Reilly Online Learning

Note

For more than 40 years, O’Reilly Media has provided technology and business training, knowledge, and insight to help companies succeed.

Our unique network of experts and innovators share their knowledge and expertise through books, articles, and our online learning platform. O’Reilly’s online learning platform gives you on-demand access to live training courses, in-depth learning paths, interactive coding environments, and a vast collection of text and video from O’Reilly and 200+ other publishers. For more information, visit http://oreilly.com.

How to Contact Us

Please address comments and questions concerning this book to the publisher:

• O’Reilly Media, Inc.
• 1005 Gravenstein Highway North
• Sebastopol, CA 95472
• 800-998-9938 (in the United States or Canada)
• 707-829-0515 (international or local)
• 707-829-0104 (fax)

We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at https://oreil.ly/lddd.

Email bookquestions@oreilly.com to comment or ask technical questions about this book.

For news and information about our books and courses, visit http://oreilly.com.

Find us on Facebook: http://facebook.com/oreilly

Follow us on Twitter: http://twitter.com/oreillymedia

Watch us on YouTube: http://youtube.com/oreillymedia

Acknowledgments

Originally, this book was titled “What Is Domain-Driven Design?” and was published as a report in 2019. Learning Domain-Driven Design would not have seen the light of day without the report, and I’m obliged to thank those who made “What Is Domain-Driven Design?” possible: Chris Guzikowski, Ryan Shaw, and Alicia Young.¹

This book also wouldn’t have been possible without O’Reilly’s Content Director and Diversity Talent Lead, Melissa Duffield, who championed the project and made it happen. Thank you, Melissa, for all your help!

Jill Leonard was the book’s development editor, project manager, and head coach. Jill’s role in this work cannot be overstated. Jill, thank you so much for all your hard work and help! Extra thanks for keeping me motivated, even when I considered changing my name and hiding in a foreign country.

A huge thanks to the production team for making the book not only writable but readable: Kristen Brown, Audrey Doyle, Kate Dullea, Robert Romano, and Katherine Tozer. For that matter, I want to thank the whole O’Reilly team for the great work you do. It’s a dream come true to be working with you!

Thanks to all the people I interviewed and consulted with: Zsofia Herendi, Scott Hirleman, Trond Hjorteland, Mark Lisker, Chris Richardson, Vaughn Vernon, and Ivan Zakrevsky. Thank you for your wisdom and for being there when I needed help!

Special thanks to the team of reviewers who read through the early drafts and helped me shape the final book: Julie Lerman, Ruth Malan, Diana Montalion, Andrew Padilla, Rodion Promyshlennikov, Viktor Pshenitsyn, Alexei Torunov, Nick Tune, Vasiliy Vasilyuk, and Rebecca Wirfs-Brock. Your support, feedback, and critique helped immensely. Thank you!

I also want to thank Kenny Baas-Schwegler, Alberto Brandolini, Eric Evans, Marco Heimeshoff, Paul Rayner, Mathias Verraes, and the rest of the amazing domain-driven design community. You know who you are. You are my teachers and mentors. Thank you for sharing your knowledge on social media, blogs, and conferences!

I’m most indebted to my dear wife, Vera, for always supporting me in my crazy projects and trying to guard me from things that could distract me from writing. I promise to finally declutter the basement. It is going to happen soon!

Finally, I want to dedicate this book to our beloved Galina Ivanovna Tyumentseva, who supported me so much in this project and whom we sadly lost during the writing of this book. We will always remember you.

#AdoptDontShop

Who Are the Domain Experts?

Now that we have a clear understanding of business domains and subdomains,

4. What is WolfDesk’s business domain?

5. What is/are WolfDesk’s core subdomain(s)?

6. What is/are WolfDesk’s supporting subdomain(s)?

7. What is/are WolfDesk’s generic subdomain(s)?

Subdomains are finer-grained problem domains whose goal

To be effective, the software has to mimic the

Figure 2-1. Knowledge sharing flow in a software project

During the traditional software development lifecycle, the domain knowledge is “translated” into an

Figure 2-2. Model transformations

Such a software development process resembles the children’s game Telephone:³ the message, or domain knowledge, often becomes distorted. The information leads to software engineers implementing the wrong solution, or the right solution but to the wrong problems. In either case, the outcome is the same: a failed software project.

Domain-driven design proposes a better way to get the knowledge from domain experts to software engineers: by using a ubiquitous language.

Figure 3-1. Example business domain: telemarketing company

An examination of the domain experts’ language reveals a peculiar observation. The term lead has different meanings in the marketing and sales departments:

Marketing department

For the marketing people, a lead represents a notification that somebody is interested in one of the products. The event of receiving the prospective customer’s contact details is considered a lead.

Sales department

In the context of the sales department, a lead is a much more complex entity. It represents the entire lifecycle of the sales process. It’s not a mere event, but a long-running process.

How do we formulate a ubiquitous language in the case of this telemarketing company?

On the one hand, we know the ubiquitous language has to be consistent—each term should have one meaning. On the other hand, we know the ubiquitous language has to reflect the domain experts’ mental models. In this case, the mental model of the “lead” is inconsistent among the domain experts in the sales and marketing departments.

This ambiguity doesn’t present that much of a challenge in person-to-person communications. Indeed, communication can be more challenging among people from different departments, but it’s easy enough for humans to infer the exact meaning from the interaction’s context.

However, it is more difficult to represent such a divergent model of the business domain in software. Source code doesn’t cope well with ambiguity. If we were to bring the sales department’s complicated model into marketing, it would introduce complexity where it’s not needed— far more detail and behavior than marketing people need for optimizing advertising campaigns. But if we were to try to simplify the sales model according to the marketing world view, it wouldn’t fit the sales subdomain’s needs, because it’s too simplistic for managing and optimizing the sales process. We’d have an overengineered solution in the first case and an under-engineered one in the second.

How do we solve this catch-22?

The traditional solution to this problem is to design a single model that can be used for all kinds of problems. Such models result in enormous entity relationship diagrams (ERDs) spanning whole office walls. Is Figure 3-2 an effective model?

Figure 3-2. Enterprise-wide entity relationship diagram

As the saying goes, “jack of all trades, master of none.” Such models are supposed to be suitable for everything but eventually are effective for nothing. No matter what you do, you are always facing complexity: the complexity of filtering out extraneous details, the complexity of finding what you do need, and most importantly, the complexity of keeping the data in a consistent state.

Another solution would be to prefix the problematic term with a definition of the context: “marketing lead” and “sales lead.” That would allow the implementation of the two models in code. However, this approach has two main disadvantages. First, it induces cognitive load. When should each model be used? The closer the implementations of the conflicting models are, the easier it is to make a mistake. Second, the implementation of the model won’t be aligned with the ubiquitous language. No one would use the prefixes in conversations. People don’t need this extra information; they can rely on the conversation’s context.

Figure 3-3. Tackling inconsistencies in the ubiquitous language by splitting it into bounded contexts

In a sense, terminology conflicts and implicit contexts are an inherent part of any decent-sized business. With the bounded context pattern, the contexts are modeled as an explicit and integral part of the business domain.

Scope of a Bounded Context

The example at the beginning of the chapter demonstrated an

inherent boundary of the business domain. Different domain experts held conflicting mental models of the same business entity. To model the business domain, we had to divide the model and define a strict applicability context for each fine-grained model—its bounded context.

The consistency of the ubiquitous language only helps to identify the widest boundary of that language. It cannot be any larger, because then there will be inconsistent models and terminology. However, we can still further decompose the models into even smaller bounded contexts, as shown in

Figure 3-4.

Figure 3-4. Smaller bounded contexts

Defining the scope of a ubiquitous language—its bounded context—is a strategic design decision.

Boundaries can be wide, following the business domain’s inherent contexts, or narrow, further dividing the business domain into smaller problem domains.

A bounded context’s size, by itself, is not a deciding factor. Models shouldn’t necessarily be big or small. Models need to be useful. The wider the boundary of the ubiquitous language is, the harder it is to keep it consistent. It may be beneficial to divide a large ubiquitous language into smaller, more manageable problem domains, but striving for small bounded contexts can backfire too. The smaller they are, the more integration overhead the design induces.

Hence, the decision for how big your bounded contexts should depend on the specific problem domain. Sometimes, using a wide boundary will be clearer, while at other times, decomposing it further will make more sense.

The reasons for extracting finer-grained bounded contexts out of a larger one include constituting new software engineering teams or addressing some of the system’s nonfunctional requirements; for example, when you need to separate the development lifecycles of some of the components originally residing in a single bounded context. Another common reason for extracting one functionality is the ability to scale it independently from the rest of the bounded context’s functionalities.

Therefore, keep your models useful and align the bounded contexts’ sizes with your business needs and organizational constraints. One thing to beware of is splitting a coherent functionality into multiple bounded contexts. Such division will hinder the ability to evolve each context independently. Instead, the same business requirements and changes will simultaneously affect the bounded contexts and require simultaneous deployment of the changes. To avoid such ineffective decomposition, use the rule of thumb we discussed in

Chapter 1 to find subdomains: identify sets of coherent use cases that operate on the same data and avoid decomposing them into multiple bounded contexts.

We’ll discuss the topic of continuously optimizing the bounded contexts’ boundaries further in Chapters 8 and 10

.

Architectural design is system design. System design is contextual design—it is inherently about boundaries (what’s in, what’s out, what spans, what moves between), and about trade-offs. It reshapes what is outside, just as it shapes what is inside.

2

The bounded context pattern is the domain-driven design tool for defining physical and ownership boundaries.

Ownership Boundaries

Studies show that good fences do indeed make good neighbors.

In software projects, we can leverage model boundaries—bounded contexts—for the peaceful coexistence of teams. The division of work between teams is another strategic decision that can be made using the bounded context pattern.

A bounded context should be implemented, evolved, and maintained by one team only. No two teams can work on the same bounded context. This segregation eliminates implicit assumptions that teams might make about one another’s models. Instead, they have to define communication protocols for integrating their models and systems explicitly.

It’s important to note that the relationship between teams and bounded contexts is one-directional: a bounded context should be owned by only one team. However, a single team can own multiple bounded contexts, as

Figure 3-8 illustrates.

Figure 3-8. Team 1 working on the Marketing and Optimization bounded contexts, while Team 2 works on the Sales bounded context

Bounded Contexts in Real Life

In one of my domain driven-design classes, a participant once

Buying a Refrigerator

Finally, let’s see a more earthbound example of real-life

bounded contexts. What do you see in

Figure 3-9?

Figure 3-9. A piece of cardboard

Is it just a piece of cardboard? No, it’s a model. It’s a model of the Siemens KG86NAI31L refrigerator. If you look it up, you may say the piece of cardboard doesn’t look anything like that fridge. It has no doors, and even its color is different.

Although that’s true, it’s not relevant. As we’ve discussed, a model is not supposed to copy a real-world entity. Instead, it should have a purpose—a problem it is supposed to solve. Hence, the correct question to ask about the cardboard is, what problem does this model solve?

In our apartment, we do not have a standard entry into the kitchen. The cardboard was cut precisely to the size of the fridge’s width and depth. The problem it solves is checking whether the refrigerator can fit through the kitchen door (see Figure 3-10).

Figure 3-10. The cardboard model in the kitchen doorway

Despite the cardboard not looking anything like the fridge, it proved extremely useful when we had to decide whether to buy this model or opt for a smaller one. Again, all models are wrong, but some are useful. Building a 3D model of the fridge would definitely be a fun project. But would it solve the problem any more efficiently than the cardboard? No. If the cardboard fits, the 3D model would fit as well, and vice versa. In software engineering terms, building a 3D model of the fridge would be gross overengineering.

But what about the refrigerator’s height? What if the base fits, but it’s too tall to fit in the doorway? Would that justify gluing together a 3D model of the fridge? No. The problem can be solved much more quickly and easily by using a simple tape measure to check the doorway’s height. What is a tape measure in this case? Another simple model.

So, we ended up with two models of the same fridge. Using two models, each optimized for its specific task, reflects the DDD approach to modeling business domains. Each model has its strict bounded context: the cardboard verifying that the refrigerator’s base can make it through the kitchen’s entry, and the tape measure verifying that it’s not too tall. A model should omit the extraneous information irrelevant to the task at hand. Also, there’s no need to design a complex jack-of-all-trades model if multiple, much simpler models can effectively solve each problem individually.

A few days after I published this story on Twitter, I received a reply saying that instead of fiddling with cardboard, I could have just used a mobile phone with a LiDAR scanner and an augmented reality (AR) application. Let’s analyze this suggestion from the domain-driven design perspective.

The author of the comment says this is a problem that others have already solved, and the solution is readily available. Needless to say, both the scanning technology and the AR application are complex. In DDD lingo, that makes the problem of checking whether the refrigerator will fit through the doorway a generic subdomain.

Figure 4-3. Customer–supplier relationship

Unlike in the cooperation case, both teams (upstream and downstream) can succeed independently.

Conformist

In some cases, the balance of power favors the upstream team,

which has no real motivation to support its clients’ needs. Instead, it just provides the integration contract, defined according to its own model—take it or leave it. Such power imbalances can be caused by integration with service providers that are external to the organization or simply by organizational politics.

If the downstream team can accept the upstream team’s model, the bounded contexts’ relationship is called conformist. The downstream conforms to the upstream bounded context’s model, as shown in

Figure 4-4.

Figure 4-4. Conformist relationship

The downstream team’s decision to give up some of its autonomy can be justified in multiple ways. For example, the contract exposed by the upstream team may be an industry-standard, well-established model, or it may just be good enough for the downstream team’s needs.

The next pattern addresses the case in which a consumer is not willing to accept the supplier’s model.

Anticorruption Layer

As in the conformist pattern, the balance of power in this relationship

is still skewed toward the upstream service. However, in this case, the downstream bounded context is not willing to conform. Instead, it can translate the upstream bounded context’s model into a model tailored to its own needs via an anticorruption layer, as shown in

Figure 4-5.

Figure 4-5. Integration through an anticorruption layer

The anticorruption layer pattern addresses scenarios in which it is not desirable or worth the effort to conform to the supplier’s model, such as the following:

When the downstream bounded context contains a core subdomain

A core subdomain’s model requires extra attention, and adhering to the supplier’s model might impede the modeling of the problem domain.

When the upstream model is inefficient or inconvenient for the consumer’s needs

If a bounded context conforms to a mess, it risks becoming a mess itself. That is often the case when integrating with legacy systems.

When the supplier’s contract changes often

The consumer wants to protect its model from frequent changes. With an anticorruption layer, the changes in the supplier’s model only affect the translation mechanism.

From a modeling perspective, the translation of the supplier’s model isolates the downstream consumer from foreign concepts that are not relevant to its bounded context. Hence, it simplifies the consumer’s ubiquitous language and model.

In Chapter 9, we will explore the different ways to implement an anticorruption layer.

Open-Host Service

This pattern addresses cases in which the power is skewed toward

the consumers. The supplier is interested in protecting its consumers and providing the best service possible.

To protect the consumers from changes in its implementation model, the upstream supplier decouples the implementation model from the public interface. This decoupling allows the supplier to evolve its implementation and public models at different rates, as shown in

Figure 4-6.

Figure 4-6. Integration through an open-host service

The supplier’s public interface is not intended to conform to its ubiquitous language.

Instead, it is intended to expose a protocol convenient for the consumers, expressed in an integration-oriented language. As such, the public protocol is called the published language.

In a sense, the open-host service pattern is a reversal of the anticorruption layer pattern: instead of the consumer, the supplier implements the translation of its internal model.

Decoupling the bounded context’s implementation and integration models gives the upstream bounded context the freedom to evolve its implementation without affecting the downstream contexts. Of course, that’s only possible if the modified implementation model can be translated into the published language the consumers are already using.

Furthermore, the integration model’s decoupling allows the upstream bounded context to simultaneously expose multiple versions of the published language, allowing the consumer to migrate to the new version gradually (see

Figure 4-7).

Figure 4-7. Open-host service exposing multiple versions of the published language

Figure 4-8. Context map

The context map is a visual representation of the system’s bounded contexts and the integrations between them. This visual notation gives valuable strategic insight on multiple levels:

High-level design

A context map provides an overview of the system’s components and the models they implement.

Communication patterns

A context map depicts the communication patterns among

teams—for example, which teams are collaborating and which prefer “less intimate” integration patterns, such as the anticorruption layer and separate ways patterns.

Organizational issues

A context map can give insight into organizational issues. For example, what does it mean if a certain upstream team’s downstream consumers all resort to implementing an anticorruption layer, or if all implementations of the separate ways pattern are concentrated around the same team?

Limitations

It’s important to note that charting a context map can be a

challenging task. When a system’s bounded contexts encompass multiple subdomains, there can be multiple integration patterns at play. For example, in

Figure 4-9, you can see two bounded contexts with two integration patterns: partnership and anticorruption layer.

Figure 4-9. Complicated context map

Moreover, even if bounded contexts are limited to a single subdomain, there still can be multiple integration patterns at play—for example, if the subdomains’ modules require different integration strategies.

Exercises

1. Which integration pattern should never be used for a core subdomain?

   1. Shared kernel

   2. Open-host service

   3. Anticorruption layer

   4. Separate ways

2. Which downstream subdomain is more likely to implement an anticorruption layer?

   1. Core subdomain

   2. Supporting subdomain

   3. Generic subdomain

   4. B and C

3. Which upstream subdomain is more likely to implement an open-host service?

   1. Core subdomain

   2. Supporting subdomain

   3. Generic subdomain

   4. A and B

4. Which integration pattern, in a sense, violates bounded contexts’ ownership boundaries?

   1. Partnership.

   2. Shared kernel.

   3. Separate ways.

   4. No integration pattern should ever break the bounded contexts’ ownership boundaries.

Transaction Script

Organizes business logic by procedures where each procedure handles a single request from the presentation.

Martin Fowler

1

A system’s public interface can be seen as a collection of business transactions that consumers can execute, as shown in Figure 5-1. These transactions can retrieve information managed by the system, modify it, or both. The pattern organizes the system’s business logic based on procedures, where each procedure implements an operation that is executed by the system’s consumer via its public interface. In effect, the system’s public operations are used as encapsulation boundaries.

Figure 5-1. Transaction script interface

DB.StartTransaction(); var job = DB.LoadNextJob(); var json = LoadFile(job.Source); var xml = ConvertJsonToXml(json); WriteFile(job.Destination, xml.ToString(); DB.MarkJobAsCompleted(job); DB.Commit()

It’s Not That Easy!

When I introduce the transaction script pattern in my domain-driven design classes, my students often raise their eyebrows, and some even ask, “Is it worth our time? Aren’t we here for the more advanced patterns and techniques?”

The thing is, the transaction script pattern is a foundation for the more advanced business logic implementation patterns you will learn in the forthcoming chapters.

Furthermore, despite its apparent simplicity, it is the easiest pattern to get wrong. A considerable number of production issues I have helped to debug and fix, in one way or another, often boiled down to a misimplementation of the transactional behavior of the system’s business logic.

Let’s take a look at three common, real-life examples of data corruption that results from failing to correctly implement a transaction script.

Lack of transactional behavior

A trivial example of failing to implement transactional behavior is to issue multiple updates without an overarching transaction. Consider the following method that updates a record in the Users table and inserts a record into the VisitsLog table:

01 public class LogVisit 02 { 03 ... 04 05 public void Execute(Guid userId, DataTime visitedOn) 06 { 07 _db.Execute("UPDATE Users SET last_visit=@p1 WHERE user_id=@p2", 08 visitedOn, userId); 09 _db.Execute(@"INSERT INTO VisitsLog(user_id, visit_date) 10 VALUES(@p1, @p2)", userId, visitedOn); 11 } 12 }

If any issue occurs after the record in the Users table was updated (line 7) but before appending the log record on line 9 succeeds, the system will end up in an inconsistent state. The Users table will be updated but no corresponding record will be written to the VisitsLog table. The issue can be due to anything from a network outage to a database timeout or deadlock, or even a crash of the server executing the process.

This can be fixed by introducing a proper transaction encompassing both data changes:

public class LogVisit { ... public void Execute(Guid userId, DataTime visitedOn) { try { _db.StartTransaction(); _db.Execute(@"UPDATE Users SET last_visit=@p1  WHERE user_id=@p2", visitedOn, userId); _db.Execute(@"INSERT INTO VisitsLog(user_id, visit_date)  VALUES(@p1, @p2)", userId, visitedOn); _db.Commit(); } catch { _db.Rollback(); throw; } } }

The fix is easy to implement due to relational databases’ native support of transactions spanning multiple records. Things get more complicated when you have to issue multiple updates in a database that doesn’t support multirecord transactions, or when you are working with multiple storage mechanisms that are impossible to unite in a distributed transaction. Let’s see an example of the latter case.

Distributed transactions

In modern distributed systems, it’s a common practice to make changes to the data in a database and then notify other components of the system about the changes by publishing messages into a message bus. Consider that in the previous example, instead of logging a visit in a table, we have to publish it to a message bus:

01 public class LogVisit 02 { 03 ... 04 05 public void Execute(Guid userId, DataTime visitedOn) 06 { 07 _db.Execute("UPDATE Users SET last_visit=@p1 WHERE user_id=@p2", 08 visitedOn,userId); 09 _messageBus.Publish("VISITS_TOPIC", 10 new { UserId = userId, VisitDate = visitedOn }); 11 } 12 }

As in the previous example, any failure occurring after line 7 but before line 9 succeeds will corrupt the system’s state. The Users table will be updated but the other components won’t be notified as publishing to the message bus has failed.

Unfortunately, fixing the issue is not as easy as in the previous example. Distributed transactions spanning multiple storage mechanisms are complex, hard to scale, error prone, and therefore are usually avoided. In

Chapter 8, you will learn how to use the CQRS architectural pattern to populate multiple storage mechanisms. In addition, Chapter 9 will introduce the outbox pattern, which enables reliable publishing of messages after committing changes to another database.

Let’s see a more intricate example of improper implementation of transactional behavior.

Implicit distributed transactions

Consider the following deceptively simple method:

public class LogVisit { ... public void Execute(Guid userId) { _db.Execute("UPDATE Users SET visits=visits+1 WHERE user_id=@p1", userId); } }

Instead of tracking the last visit date as in the previous examples, this method maintains a counter of visits for each user. Calling the method increases the corresponding counter’s value by 1. All the method does is update one value, in one table, residing in one database. Yet this is still a distributed transaction that can potentially lead to inconsistent state.

This example constitutes a distributed transaction because it communicates information to the databases and the external process that called the method, as demonstrated in Figure 5-2.

Figure 5-2. The LogVisit operation updating the data and notifying the caller of the operation’s success or failure

Although the execute method is of type void, that is, it doesn’t return any data, it still communicates whether the operation has succeeded or failed: if it failed, the caller will get an exception.

What if the method succeeds, but the communication of the result to the caller fails? For example:

• If LogVisit is part of a REST service and there is a network outage; or

• If both LogVisit and the caller are running in the same process, but the process fails before the caller gets to track successful execution of the LogVisit action?

In both cases, the consumer will assume failure and try calling LogVisit again. Executing the LogVisit logic again will result in an incorrect increase of the counter’s value. Overall, it will be increased by 2 instead of 1. As in the previous two examples, the code fails to implement the transaction script pattern correctly, and inadvertently leads to corrupting the system’s state.

As in the previous example, there is no simple fix for this issue. It all depends on the business domain and its needs. In this specific example, one way to ensure transactional behavior is to make the operation idempotent: that is, leading to the same result even if the operation repeated multiple times.

For example, we can ask the consumer to pass the value of the counter. To supply the counter’s value, the caller will have to read the current value first, increase it locally, and then provide the updated value as a parameter. Even if the operation will be executed multiple times, it won’t change the end result:

public class LogVisit { ... public void Execute(Guid userId, long visits) { _db.Execute("UPDATE Users SET visits = @p1 WHERE user_id=@p2", visits, userId); } }

Another way to address such an issue is to use optimistic concurrency control: prior to calling the LogVisit operation, the caller has read the counter’s current value and passed it to LogVisit as a parameter. LogVisit will update the counter’s value only if it equals the one initially read by the caller:

public class LogVisit { ... public void Execute(Guid userId, long expectedVisits) { _db.Execute(@"UPDATE Users SET visits=visits+1  WHERE user_id=@p1 and visits = @p2", userId, visits); } }

Subsequent executions of LogVisit with the same input parameters won’t change the data, as the WHERE...visits = @prm2 condition won’t be fulfilled.

When to Use Transaction Script

The transaction script pattern is well adapted to the most straightforward

problem domains in which the business logic resembles simple procedural operations. For example, in extract-transform-load (ETL) operations, each operation extracts data from a source, applies transformation logic to convert it into another form, and loads the result into the destination store. This process is shown in

Figure 5-3.

Figure 5-3. Extract-transform-load data flow

The transaction script pattern naturally fits supporting subdomains where, by definition, the business logic is simple. It can also be used as an adapter for integration with external systems—for example, generic subdomains, or as a part of an anticorruption layer (more on that in Chapter 9).

The main advantage of the transaction script pattern is its simplicity. It introduces minimal abstractions and minimizes the overhead both in runtime performance and in understanding the business logic. That said, this simplicity is also the pattern’s disadvantage. The more complex the business logic gets, the more it’s prone to duplicate business logic across transactions, and consequently, to result in inconsistent behavior—when the duplicated code goes out of sync. As a result, transaction script should never be used for core subdomains, as this pattern won’t cope with the high complexity of a core subdomain’s business logic.

This simplicity earned the transaction script a dubious reputation. Sometimes the pattern is even treated as an antipattern. After all, if complex business logic is implemented as a transaction script, sooner rather than later it’s going to turn into an unmaintainable, big ball of mud. It should be noted, however, that despite the simplicity, the transaction script pattern is ubiquitous in software development. All the business logic implementation patterns that we will discuss in this and the following chapters, in one way or another, are based on the transaction script pattern.

An object that wraps a row in a database table or view, encapsulates the database access, and adds domain logic on that data.

Martin Fowler

2

Like the transaction script pattern, active record supports cases where the business logic is simple. Here, however, the business logic may operate on more complex data structures. For example, instead of flat records, we can have more complicated object trees and hierarchies, as shown in Figure 5-4.

Figure 5-4. A more complicated data model with one-to-many and many-to-many relationships

Operating on such data structures via a simple transaction script would result in lots of repetitive code. The mapping of the data to an in-memory representation would be duplicated all over.

public class CreateUser { ... public void Execute(userDetails) { try { _db.StartTransaction(); var user = new User(); user.Name = userDetails.Name; user.Email = userDetails.Email; user.Save(); _db.Commit(); } catch { _db.Rollback(); throw; } } }

History

As with both the transaction script and active record patterns, the

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 Brooks

1

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.

It’s evident that the table is used to manage potential customers, or leads, in a telemarketing 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 demonstrates 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 submitted 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 modeled in the table in Table 7-1.

Pay attention to the Version field

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; } }

LeadId: 12 FirstNames: ['Casey'] LastNames: ['David', 'Davis'] PhoneNumbers: ['555-2951', '555-8101'] Version: 6

public class AnalysisModelProjection { public long LeadId { get; private set; } public int Followups { get; private set; } public LeadStatus Status { get; private set; } public int Version { get; private set; } public void Apply(LeadInitialized @event) { LeadId = @event.LeadId; Followups = 0; Status = LeadStatus.NEW_LEAD; Version = 0; } public void Apply(Contacted @event) { Version += 1; } public void Apply(FollowupSet @event) { Status = LeadStatus.FOLLOWUP_SET; Followups += 1; Version += 1; } public void Apply(ContactDetailsChanged @event) { Version += 1; } public void Apply(OrderSubmitted @event) { Status = LeadStatus.PENDING_PAYMENT; Version += 1; } public void Apply(PaymentConfirmed @event) { Status = LeadStatus.CONVERTED; Version += 1; } }

LeadId: 12 Followups: 1 Status: Converted Version: 6

Source of Truth

For the event sourcing pattern to work, all changes to an object’s state

should be represented and persisted as events. These events become the system’s source of truth (hence the name of the pattern). This process is shown in

Figure 7-1.

Figure 7-1. Event-sourced aggregate

The database that stores the system’s events is the only strongly consistent storage: the system’s source of truth. The accepted name for the database that is used for persisting events is event store.

interface IEventStore { IEnumerable<Event> Fetch(Guid instanceId); void Append(Guid instanceId, Event[] newEvents, int expectedVersion); }

The application service follows the script described earlier: it loads the relevant ticket’s events, rehydrates the aggregate instance, calls the relevant command, and persists changes back to the database:

01 public class TicketAPI 02 { 03 private ITicketsRepository _ticketsRepository; 04 ... 05 06 public void RequestEscalation(TicketId id, EscalationReason reason) 07 { 08 var events = _ticketsRepository.LoadEvents(id); 09 var ticket = new Ticket(events); 10 var originalVersion = ticket.Version; 11 var cmd = new RequestEscalation(reason); 12 ticket.Execute(cmd); 13 _ticketsRepository.CommitChanges(ticket, originalVersion); 14 } 15 16 ... 17 }

The Ticket aggregate’s rehydration logic in the constructor (lines 27 through 31) instantiates an instance of the state projector class, TicketState, and sequentially calls its AppendEvent method for each of the ticket’s events:

18 public class Ticket 19 { 20 ... 21 private List<DomainEvent> _domainEvents = new List<DomainEvent>(); 22 private TicketState _state; 23 ... 24 25 public Ticket(IEnumerable<IDomainEvents> events) 26 { 27 _state = new TicketState(); 28 foreach (var e in events) 29 { 30 AppendEvent(e); 31 } 32 }

The AppendEvent passes the incoming events to the TicketState projection logic, thus generating the in-memory representation of the ticket’s current state:

33 private void AppendEvent(IDomainEvent @event) 34 { 35 _domainEvents.Append(@event); 36 // Dynamically call the correct overload of the "Apply" method. 37 ((dynamic)state).Apply((dynamic)@event); 38 }

Contrary to the implementation we saw in the previous chapter, the event-sourced aggregate’s RequestEscalation method doesn’t explicitly set the IsEscalated flag to true. Instead, it instantiates the appropriate event and passes it to the AppendEvent method (lines 43 and 44):

39 public void Execute(RequestEscalation cmd) 40 { 41 if (!_state.IsEscalated && _state.RemainingTimePercentage <= 0) 42 { 43 var escalatedEvent = new TicketEscalated(_id, cmd.Reason); 44 AppendEvent(escalatedEvent); 45 } 46 } 47 48 ... 49 }

All events added to the aggregate’s events collection are passed to the state projection logic in the TicketState class, where the relevant fields’ values are mutated according to the events’ data:

50 public class TicketState 51 { 52 public TicketId Id { get; private set; } 53 public int Version { get; private set; } 54 public bool IsEscalated { get; private set; } 55 ... 56 public void Apply(TicketInitialized @event) 57 { 58 Id = @event.Id; 59 Version = 0; 60 IsEscalated = false; 61 .... 62 } 63 64 public void Apply(TicketEscalated @event) 65 { 66 IsEscalated = true; 67 Version += 1; 68 } 69 70 ... 71 }

Now let’s look at some of the advantages of leveraging event sourcing when implementing complex business logic.

Frequently Asked Questions

When engineers are introduced to the event sourcing pattern, they often ask several common questions, so I find it obligatory to address them in this chapter.

Business Logic Versus Architectural Patterns

Business logic is the most important part of software; however,