Dive into DDD – Part II

After presenting the fundamentals of DDD in the Part I of this Dive into DDD series, it is time we got our hands dirty with some practice.

As I mentioned there, the purpose of the examples I am going to introduce in this series is not only to illustrate how to produce software under the principles of DDD, but also how to make it with PHP 7. However, do not hesitate to produce your own solutions to the case using the language you choose, because, as a methodology, DDD is not linked to any specific language or framework.

The case

During our very first conversation within the team of people in charge of distilling the Domain, and produce the software to represent it, we were able to collect the following summary of information:

We, ACME CORPORATION, run a digital store of products and services on behalf of other companies, our Providers.

After signing up on our site, Customers may order one or more items at a time, from the whole Catalogue available.

Occasionally, we may offer them discounts based on different conditions (for instance, because they may be living in a country we are interested in increasing our market share; by ordering specific items, by ordering at least a given number of units, by reaching a given total order amount, on special dates, etc.).

Our sales spread over twenty countries in two continents. We buy and sale under five currencies, and our site runs eight languages.

How should be start exploring this, or any other, Domain? I am presenting a technique and a couple of tools just in a minute, but before I’d like to remark that Exploring a Domain is a creative activity similar to play a music instrument or writing tales: you may learn the basics from others, but ultimately you would need to acquire your own style and pool of techniques, and to adapt them to the particular needs in place.

Now, back to the case, let’s avoid the mistake of restricting ourselves to the obvious, and the obvious mistake here is to think of the Domain as limited to an e-commerce site. Beyond customers, actual and potential, the items on sale, and their providers, there is more at stake here not to forget.

So let’s keep our eyes and ears wide open and start exploring.

In 101 of Domain Exploration, the teacher’s advice is to draw what is called a Context Map. A Context map is a picture showing all the bounded contexts in the Domain, for instance, as labels enclosed into rectangles or circles, and arrows or similar depicting the relationships among them. You may show them closer if they are functionally closer too; even though, a Context Map is not the place to display actual processes, for processes belong to a lower, more detailed level of knowledge.

A Context Map is the broader, higher level vision of the Domain you might picture.

To draw a Context Map is an excellent activity whenever a new DDD project starts. It is also a great tool to rely on whenever a summary of the project has to be displayed to upper levels of the company, in internal events, etc.

Why not we produce a Context Map for this case? Below I put an example depicting just a brief list of apparently relevant (at least, to me) bounded contexts.

The Domain Vision Statement

As long as you explore deeper and deeper the Domain, you may version a collection of Context Maps. Some talks may enrich the Context Map in unexpected directions, drawing new bounded contexts and relations, while other conversations may end with some bounded contexts split or joined.

However enlightening, to explore the domain is not an activity meant to merely increase our knowledge, but to support our creation of new quality software, and to produce software the team must focus on something.

So an improved procedure for Domain Exploration is to highlight the center (the core) of the Domain and organise the bounded contexts according to their relationship to the core.

Teams often write a sentence which states the main value provided by the Domain, which is its purpose, and pinpoints the direction to which further software features should go. This sentence is often called the Domain Vision Statement.

To achieve an agreement on a Domain Vision Statement may be easy for some teams, and almost impossible for others. No matter the words of the Statement eventually agreed upon, it must suggest which is the central core of the Domain, otherwise it is not only useless, even counterproductive.

In our example, and under my personal point of view, the value provided by a store comes from the catalog of products available for sale, for these items are the reason why customers may sign up and buy. Therefore, the Domain Vision Statement may be to Provide a rich catalogue of products and services for sale to the markets the company perceives as profitable.

Therefore, the Item bounded context in the Context Map above is, in my opinion, key to the Domain. That puts it in the core, for nothing else looks more central.

Likely other bounded contexts will be part of the core as well, whereas others would be classified as supporting bounded contexts. For instance, Orders, which stands for to the whole Order fulfilment process, looks quite central to me as well; instead, Taxes looks secondary.

A first sketch of the Ubiquitous Language

During that first conversation, the team must be able to produce a brief list of terms as the Domain’s Ubiquitous Language. This is my version of it:

ACME’s Domain Ubiquitous Language

• Discount: money we cease to take from Customers in her Orders under certain conditions particular to every Discount. The money discounted must be less, or equal, the Unit Gross Margin either of the Item deserving that Discount, or the Gross Margin of the whole Order.
• Item: every product or service a Customer may buy. The same Item might be purchased to more than one Provider.
• Order: every unique operation of purchase made by Customers in our site.
• Provider: the organisation in charge of providing us with the Items we sell. We’ll need to pay them for those Items according to the specifics of Purchase Agreement signed with them.
• Purchase agreement: list of conditions agreed with a Provider. It holds prices, delivery terms, quality assurances, an any other conditions either the Provider or we consider relevant for our mutual operations.
• Tax: money we collect from the Customers in their Orders on behalf of the local administration.
• Unit Price: the amount of money a Customer would need to pay for one unit of a given Item, before any discount and Taxes may be applied.
• Unit Cost: the total amount of money we must spend for an Item, i.e., the money we should pay the Provider for one unit of the Item, etc.
• Unit Gross Margin: the result of subtracting the Unit Cost from the Unit Price. It is commonly understood as a percentage, though it may be represented otherwise.

As we saw in Part I of this series, the Ubiquitous Language is an evolving creature which not only sets the ground for the whole DDD methodology to rely on, a goal which claims for stability, but its openness to improvement also acts as a driver for further talks, a purpose which claims for variability. Such a magnificent instrument it is!

To Do List

What’s next? We need to implement a persistence layer for at least three different Entities: Items, Providers, and Purchase Agreements. They are the constituents of our Domain so far.

So far I am making use of the common meaning of Entity, i.e., as a unit of persistence. In the Part III of this series I will state a more proper definition of Entity, as it is used in the reign of DDD.

We also need to implement a View showing a list of available Items for sale, which is going to be part of a UI layer. In the context of a Request and Response model, we should also implement a Controller function.

This all is a powerful remembering of the Model View Controller (MVC) pattern. No matter how old-fashioned, MVC it is such a common, and language agnostic, design pattern in the software community that it just looks suitable to pick it here. Later on in this series, we will see other ways to organise our software which fit better with DDD.

So, our To Do List should be like this:

• 3 models (Item, Provider, and Purchase Agreement),
• 1 View (Product Catalogue),
• and 1 Controller (GET the Product Catalogue).

We will review my code, produced according to what we have seen in Part I and Part II of this series, in its next instalment, in which we are also going to learn a lot more about DDD.

So, let’s code, and see ya in Part III of this series!