In this chapter we’ll look into how we can model business processes with code, in a way that’s highly compatible with TDD. We’ll discuss why domain modelling matters, and we’ll look at a few key patterns for modelling domains: Entities, Value Objects, and Domain Services.
In the [introduction], we used the term business logic layer to describe the central layer of a three-layered architecture. For the rest of the book, we’re going to use the term Domain Model instead. This is a term from the DDD community that does a better job of capturing our intended meaning (see the next sidebar for more on DDD).
The domain is a fancy way of saying the problem you’re trying to solve. We currently work for an online retailer of furniture. Depending on which system I’m talking about, the domain might be purchasing and procurement, or product design, or logistics and delivery. Most programmers spend their days trying to improve or automate business processes; the domain is the set of activities that those processes support.
A model is a map of a process or phenomenon that captures some useful property. Humans are exceptionally good at producing models of things in their heads. For example, when someone throws a ball toward you, you’re able to predict its movement almost unconsciously, because you have a model of how objects move in space. Your model isn’t perfect by any means. Humans have terrible intuitions about how objects behave at near-light speeds or in a vacuum because our model was never designed to cover those cases. That doesn’t mean the model is wrong, but it does mean that some predictions fall outside of its domain.
Domain-driven design, or DDD, is where the concept of domain modelling was popularized,[1] and it’s been a hugely successful movement in transforming the way people design software by focusing on the core business domain. Many of the architecture patterns that we cover in this book, like Entity, Aggregate and Value Objects (see [chapter_05_uow]), and Repository pattern (in the next chapter) all come from the DDD tradition.
In a nutshell, DDD says that the most important thing about software is that it provides a useful model of some problem. If we get that model right, then our software delivers value and makes new things possible.
If we get it wrong, it becomes an obstacle to be worked around. In this book we can show the basics of building a domain model, and building an architecture around it that leaves the model as free as possible from external constraints, so that it’s easy to evolve and change.
But there’s a lot more to DDD, and the processes, tools and techniques for developing a domain model. We hope to give you a taste for it though, and cannot encourage you enough to go on and read a proper DDD book.
-
The original "blue book", Domain-Driven Design by Eric Evans (Addison-Wesley, 2003)
-
Or, some people prefer the "red book", Implementing Domain-Driven Design, by Vaughn Vernon (Addison-Wesley, 2013).
The Domain Model is the mental map that business owners have of their businesses. All business people have these mental maps, they’re how humans think about complex processes.
You can tell when they’re navigating these maps because they use business speak. Jargon arises naturally between people who are collaborating on complex systems.
Imagine that you, our unfortunate reader, were suddenly transported light years away from Earth aboard an alien spaceship with your friends and family and had to figure out, from first principles, how to navigate home.
In your first few days, you might just push buttons randomly, but soon you’d learn which buttons did what, so that you could give one another instructions. "Press the red button near the flashing doo-hickey and then throw that big lever over by the radar gizmo," you might say.
Within a couple of weeks, you’d become more precise as you adopted words to describe the ship’s functions: "increase oxygen levels in cargo bay three" or "turn on the little thrusters." After a few months you’d have adopted language for entire complex processes: "Start landing sequence," or "prepare for warp." This process would happen quite naturally, without any formal effort to build a shared glossary.
So it is in the mundane world of business. The terminology used by business stakeholders represents a distilled understanding of the domain model, where complex ideas and processes are boiled down to a single word or phrase.
When we hear our business stakeholders using unfamiliar words, or using terms in a specific way, we should listen to understand the deeper meaning and encode their hard-won experience into our software.
We’re going to use a real-world domain model throughout this book, specifically a model from our current employment. Made.com is a successful furniture retailer. We source our furniture from manufacturers all over the world and sell it across Europe.
When you buy a sofa or a coffee table, we have to figure out how best to get your goods from Poland or China or Vietnam, and into your living room.
At a high level, we have separate systems that are responsible for buying stock, selling stock to customers, and shipping goods to customers. There’s a system in the middle that needs to coordinate the process by allocating stock to a customer’s orders; see Context diagram for the allocation service.
[plantuml, allocation_context_diagram] @startuml Allocation Context Diagram !includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4.puml !includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Context.puml System(systema, "Allocation", "Allocates stock to customer orders") Person(customer, "Customer", "Wants to buy furniture") Person(buyer, "Buying Team", "Needs to purchase furniture from suppliers") System(procurement, "Purchasing", "Manages workflow for buying stock from suppliers") System(ecom, "E-commerce", "Sells goods online") System(warehouse, "Warehouse", "Manages workflow for shipping goods to customers.") Rel(buyer, procurement, "Uses") Rel(procurement, systema, "Notifies about shipments") Rel(customer, ecom, "Buys from") Rel(ecom, systema, "Asks for stock levels") Rel(ecom, systema, "Notifies about orders") Rel_R(systema, warehouse, "Sends instructions to") Rel_U(warehouse, customer, "Dispatches goods to") @enduml
For the purposes of this book, we’re imagining a situation where the business decides to implement an exciting new way of allocating stock. Until now, the business has been presenting stock and lead times based on what is physically available in the warehouse. If and when the warehouse runs out, a product is listed as "out of stock" until the next shipment arrives from the manufacturer.
The innovation is: if we have a system that can keep track of all our shipments and when they’re due to arrive, then we can treat the goods on those ships as real stock, and part of our inventory, just with slightly longer lead times. Fewer goods will appear to be out of stock, we’ll sell more, and the business can save money by keeping lower inventory in the domestic warehouse.
But allocating orders is no longer a trivial matter of decrementing a single quantity in the warehouse system. We need a more complex allocation mechanism. Time for some domain modelling.
Understanding the domain model takes time, and patience, and post-it notes. We have an initial conversation with our business experts and we agree on a glossary and some rules for the first minimal version of the domain model. Wherever possible, we ask for concrete examples to illustrate each rule.
We make sure to express those rules in the business jargon (the "ubiquitous language" in DDD terminology). We choose memorable identifiers for our objects so that the examples are easier to talk about.
Here are some notes we might have taken while having a conversation with our domain experts about allocation.
-
A product is identified by a sku, pronounced "skew," which is short for "Stock Keeping Unit."
-
Customers place orders. An order is identified by an order reference, and comprises multiple order lines, where each line has a sku, and a quantity.
Example:-
10 units of RED-CHAIR
-
1 unit of TASTELESS-LAMP
-
-
The purchasing department orders small batches of stock. A batch of stock has a unique id which they call a reference, a sku and a quantity.
-
We need to allocate order lines to batches. When we’ve allocated an order line to a batch, we will send stock from that specific batch to the customer’s delivery address.
-
When we allocate 1 unit of stock to a batch, the available quantity is reduced.
Example:-
We have a batch of 20 SMALL-TABLE, and we allocate an order line for 2 SMALL-TABLE.
-
The batch should have 18 SMALL-TABLE remaining.
-
-
We can’t allocate to a batch if the available quantity is less than the quantity of the order line.
Example:-
We have a batch of 1 BLUE-CUSHION, and an order line for 2 BLUE-CUSHION.
-
We should not be able to allocate the line to the batch.
-
-
We can’t allocate the same line twice.
Example:-
We have a batch of 10 BLUE-VASE, and we allocate an order line for 2 BLUE-VASE.
-
If we allocate the order line again to the same batch, the batch should still have an available quantity of 8.
-
-
Batches have an ETA if they are currently shipping, or they may be in Warehouse stock.
-
We allocate to warehouse stock in preference to shipment batches
-
We allocate to shipment batches in order of which has the earliest ETA.
Why not have a go at solving this problem yourself? Write a few unit tests and see if you can capture the essence of these business rules in some nice, clean code.
We’ve got some placeholder unit tests here, but you could just start from scratch, or combine/rewrite these however you like:
We’re not going to show you how TDD works in this book, but we want to show you how we would construct a model from this business conversation.
Here’s what one of our first tests might look like:
def test_allocating_to_a_batch_reduces_the_available_quantity():
batch = Batch("batch-001", "SMALL-TABLE", qty=20, eta=date.today())
line = OrderLine('order-ref', "SMALL-TABLE", 2)
batch.allocate(line)
assert batch.available_quantity == 18The name of our unit test describes the behavior that we want to see from the system, and the names of the classes and variables that we use are taken from the business jargon. We could show this code to our non-technical co-workers, and they would agree that this correctly describes the behavior of the system.
And here is a domain model that meets our requirements:
@dataclass(frozen=True) #(1)
class OrderLine:
orderid: str
sku: str
qty: int
class Batch:
def __init__(
self, ref: str, sku: str, qty: int, eta: Optional[date] #(2)
):
self.reference = ref
self.sku = sku
self.eta = eta
self.available_quantity = qty
def allocate(self, line: OrderLine):
self.available_quantity -= line.qty-
OrderLineis an immutable dataclass[2] with no behavior. -
Type hints are still a matter of controversy in the Python world. For domain models, they can sometimes help to clarify or document what the expected arguments are, and people with IDEs are often grateful for them. You may decide the price paid in terms of readability is too high.
Our implementation here is trivial: a Batch just wraps an integer
available_quantity and we decrement that value on allocation. We’ve written
quite a lot of code just to subtract one number from another, but we think that
modelling our domain precisely will pay off.
Let’s write some new failing tests:
def make_batch_and_line(sku, batch_qty, line_qty):
return (
Batch("batch-001", sku, batch_qty, eta=date.today()),
OrderLine("order-123", sku, line_qty)
)
def test_can_allocate_if_available_greater_than_required():
large_batch, small_line = make_batch_and_line("ELEGANT-LAMP", 20, 2)
assert large_batch.can_allocate(small_line)
def test_cannot_allocate_if_available_smaller_than_required():
small_batch, large_line = make_batch_and_line("ELEGANT-LAMP", 2, 20)
assert small_batch.can_allocate(large_line) is False
def test_can_allocate_if_available_equal_to_required():
batch, line = make_batch_and_line("ELEGANT-LAMP", 2, 2)
assert batch.can_allocate(line)
def test_cannot_allocate_if_skus_do_not_match():
batch = Batch("batch-001", "UNCOMFORTABLE-CHAIR", 100, eta=None)
different_sku_line = OrderLine("order-123", "EXPENSIVE-TOASTER", 10)
assert batch.can_allocate(different_sku_line) is False/// [SG] so is why you are not putting imports in like from datetime import date because now you need to import Batch and OrderLine and you do not want to tell people where to put these in their project structure? from yourproject.domain.models import Batch, OrderLine ///
There’s nothing too unexpected here. We’ve refactored our test suite so that we
don’t keep repeating the same lines of code to create a batch and a line for
the same sku; and we’ve written four simple tests for a new method
can_allocate. Again, notice that the names we use mirror the language of our
domain experts, and the examples we agreed upon are directly written into code.
We can implement this straightforwardly, too, by writing the can_allocate
method of Batch.
def can_allocate(self, line: OrderLine) -> bool:
return self.sku == line.sku and self.available_quantity >= line.qtySo far we can manage the implementation by just incrementing and decrementing
Batch.available_quantity, but as we get into deallocate() tests, we’ll be
forced into a more intelligent solution:
def test_can_only_deallocate_allocated_lines():
batch, unallocated_line = make_batch_and_line("DECORATIVE-TRINKET", 20, 2)
batch.deallocate(unallocated_line)
assert batch.available_quantity == 20In this test we’re asserting that deallocating a line from a batch has no effect
unless the batch previously allocated the line. For this to work, our Batch
needs to understand which lines have been allocated. Let’s look at the
implementation:
class Batch:
def __init__(
self, ref: str, sku: str, qty: int, eta: Optional[date]
):
self.reference = ref
self.sku = sku
self.eta = eta
self._purchased_quantity = qty
self._allocations = set() # type: Set[OrderLine]
def allocate(self, line: OrderLine):
if self.can_allocate(line):
self._allocations.add(line)
def deallocate(self, line: OrderLine):
if line in self._allocations:
self._allocations.remove(line)
@property
def allocated_quantity(self) -> int:
return sum(line.qty for line in self._allocations)
@property
def available_quantity(self) -> int:
return self._purchased_quantity - self.allocated_quantity
def can_allocate(self, line: OrderLine) -> bool:
return self.sku == line.sku and self.available_quantity >= line.qty[SG] If the batch cannot be allocated, the allocate method just returns without complaint. I would prefer to know if I tried to allocate to a batch and I was not able to. Was it because I targeted the wrong batch for my sku? Was it because the batch was exhausted?
[SG] Wouldn’t it be nicer to create a batch of SMALL-FORK then allocate them all then try to allocate one more to see the exception. This test makes me think for goodness sake you are just targeting the wrong batch.