JavaScript Domain-Driven Design

Running an orc dungeon seems pretty simple from the outside, but managing it without getting killed is actually rather complicated. For this reason, we are contacted by an orc master who struggles with keeping his dungeon running smoothly. When we arrive at the dungeon, he explains to us how it actually works and what factors come into play.

Many outside factors play a role and the dungeon is not as independent at it would like to be. After all, it is part of the orc kingdom, and the king demands that his dungeons make him money. However, money is just part of the deal. How does it actually make money? The prisoners need to mine gold and to do that there needs to be a certain amount of prisoners in the dungeon that need to be kept. The way an orc kingdom is run also results in the constant arrival of new prisoners, new captures from war, those who couldn't afford their taxes, and so on. There always needs to be room for new prisoners. The good thing is that every dungeon is interconnected, and to achieve its goals it can rely on others by requesting a prisoner transfer to either fill up free cells or get rid of overflowing prisoners in its cells. These options allow the dungeon masters to keep a close watch on prisoners being kept and the amount of cell space available. Sending off prisoners into other dungeons as needed and requesting new ones from other dungeons, in case there is too much free cell space available, keeps the mining workforce at an optimal level for maximizing the profit, while at the same time being ready to accommodate the eventual arrival of a high value inmate sent directly to the dungeon. So far, the explanation is sound, but let's dig a little deeper and see what is going on.

To create a good understanding of what a piece of software needs to do, at least to be useful in the best way, is to get an understanding of what the future users were doing before your software existed. Therefore, we sit down with the orc master as he is managing his incoming and outgoing prisoners, and let him walk us through what he is doing on a day-to-day basis.

The dungeon is comprised of 100 cells that are either occupied by a prisoner or empty at the moment. When managing these cells, we can identify distinct tasks by watching the orc do his job. Drawing out what we see, we can roughly sketch it like this:

There are a couple of organizational important events and states to be tracked, they are:

Each transfer can be in multiple states that the master has to know about to make further decisions on what to do next. Keeping a view of the world like this is not easy especially accounting for the amount of concurrent updates happening. Tracking the state of everything results in further tasks for our master to do:

So, what does each of them involve?

Of course there are many other ways to get started, but what it boils down to in most cases is that it is time now to choose the base to build on. By this I mean deciding on a framework or set of libraries to build upon. This happens alongside the decision on what database is used to back our application and many other small decisions, which are influenced by influenced by those decisions around framework and libraries. A clear understanding on how the frontend should be built is important as well, since building a single-page application, which implements a large amount of logic in the frontend and is backed by an API layer that differs a lot from an application, which implements most logic on the server side.

Since we don't have a clear understanding, yet, which way the application will ultimately take, we try to push as many decisions as possible out, but decide on the stuff we immediately need. As we are developing in JavaScript, the application is going to be developed in Node.js and express is going to be our framework of choice. To make our life easier, we first decide that we are going to implement the frontend in plain HTML using EJS embedded JavaScript templates, since it will keep the logic in one place. This seems sensible since spreading the logic of a complex application across multiple layers will complicate things even further. Also, getting rid of the eventual errors during transport will ease our way toward a solid application in the beginning. We can push the decision about the database out and work with simple objects stored in RAM for our first prototype; this is, of course, no long-term solution, but we can at least validate some structure before we need to decide on another major piece of software, which brings along a lot of expectations as well. With all this in mind, we setup the application.

In the following section and throughout the book, we are using Node.js to build a small backend. At the time of the writing, the currently active version was Node.js 0.10.33. Node.js can be obtained from http://nodejs.org/ and is available for Windows, Mac OS X, and Linux. The foundation for our web application is provided by express, available via the Node Package Manager (NPM) at the time of writing in version 3.0.3:

$ npm install –g express
$ express --ejs inmatr

var Dungeon = function(cells) {
  this.cells = cells
  this.bookedCells = 0
}

var dungeons = {}
Dungeon.find = function(id, callback) {
  if(!dungeons[id]) {
    dungeons[id] = new Dungeon(100)
  }
  callback(null, dungeons[id])
}

function(req, res, next) {
  req.context = req.context || {}
  Dungeon.find('main', function(err, dungeon) {
    req.context.dungeon = dungeon
    next()
  })
}

<h1>Inmatr</h1>
<p>You currently have <%= dungeon.free %> of
<%= dungeon.cells %> cells available.</p>

<form action="/cells/book" method="post">
  <select name="cells">
    <% for(var i = 1; i < 11; i++) { %>
    <option value="<%= i %>"><%= i %></option>
  <% } %>
  </select>
  <button type="submit" name="book" value="book">
  Book cells</button>
  <button type="submit" name="free" value="free">
  Free cells</button>
</form>

Gluing the application together via express

Now that we are almost done, we have a display for the state, a model to track what is changing, and a middleware to load this model as needed. Now, to glue it all together we will use express to register our routes and call the necessary functions. We mainly need two routes: one to display the page and one to accept and process the form input. Displaying the page is done when a user hits the index page, so we need to bind to the root path. Accepting the form input is already declared in the form itself as /cells/book. We can just create a route for it. In express, we define routes in relation to the main app object and according to the HTTP verbs as follows:

app.get('/', routes.index)
app.post('/cells/book', routes.cells.book)

Adding this to the main app.js file allows express to wire things up, the routes itself are implemented as follows in the routes/index.js file:

var routes = {
  index: function(req, res){
    res.render('index', req.context)
  },

cells: {
  book: function(req, res){
    var dungeon = req.context.dungeon
    var cells = parseInt(req.body.cells)
    if (req.body.book) {
    dungeon.book(cells)
  } else {
    dungeon.unbook(cells)
  }

      res.redirect('/')
    }
  }
}

With this done, we have a working application to track free and used cells.

The following shows the frontend output for the tracking system:

This is only the first step toward the application that will hopefully automate what is currently done by hand. With the first start in place, it is now time to make sure we can move the application along. We have to think about what this application is supposed to do and identify the next steps. After presenting the current state back to the business the next request is most likely to be to integrate some kind of login, since it will not be possible to modify the state of the dungeon unless you are authorized to do it. Since this is a web application, most people are familiar with them having a login. This moves us into a complicated space in which we need to start specifying the roles in the application along with their access patterns; so it is not clear if this is the way to go.

Another route to take is starting to move the application towards tracking events instead of pure numbers of the free cells. From a developer's point of view, this is probably the most interesting route but the immediate business value might be hard to justify, since without the login it seems unusable. We need to create an endpoint to record events such as fleeing prisoner, and then modify the state of the dungeon according to those tracked events. This is based on the assumption that the highest value for the application will lie in the prediction of the prisoner movement. When we want to track free cells in such a way, we will need to modify the way our first version of the application works. The logic on what events need to be created will have to move somewhere, most logically the frontend, and the dungeon will no longer be the single source of truth for the dungeon state. Rather, it will be an aggregator for the state, which is modified by the generation of events.

Thinking about the application in such a way makes some things clear. We are not completely sure what the value proposition of the application ultimately will be. This leads us down a dangerous path since the design decisions that we make now will impact how we build new features inside the application. This is also a problem in case our assumption about the main value proposition turns out to be wrong. In this case, we may have built quite a complex event tracking system which does not really solve the problem but complicates things. Every state modification needs to be transformed into a series of events where a simple state update on an object may have been enough. Not only does this design not solve the real problem, explaining it to the orc master is also tough. There are certain abstractions missing, and the communication is not following a pattern established as the business language. We need an alternative approach to keep the business more involved. Also, we need to keep development simple using abstraction on the business logic and not on the technologies, which are provided by the frameworks that are used.

So far, we have been thinking about the problem in terms of a Model-View-Controller (MVC), web application. This brings along a certain set of assumptions that might not hold true in the case of our business domain. It is true that creating a web interface to manage input and output often does handle the presentation of an application today, but this does not mean that this part also holds the primary set of logic. In the case of our dungeon manager, it might only be one way to access and input data. An information system structured in this way has models holding the logic along with the data. These models are backed by a database, which is responsible for persistence, and is also used to implement some logic via constraints on the data. This means that our domain is pressed in the shape of the, most likely relational, database model.

All this locks us into a certain set of technologies: a webserver for hosting our application, a database for persistence, and a web layer for access and input. All these elements become the integral parts of our application and make change hard. Also, the model layer has no real abstraction besides being composed of a bunch of models. When we want to represent more complex interactions, this might not be enough. To be clear, there is no real issue with this as long as the developed application primarily consists of the interaction between systems, when however, the value proposition is mainly the business logic to be represented between parts of the system, this design starts to be not enough anymore.

In the case of business applications, a lot of problems and their respective solutions are often not explicit. This is true for many areas and an example most developers might be familiar with is setting up a webserver. When asking a developer or administrator what he has to do to achieve this, it is described in only a few steps along the lines of: set up the operating system, install Apache, configure the site, and then start. For another developer of a system administrator, this might be enough to know what to do, but this is hardly reproducible for somebody from the outside or, even worse, for a computer.

Making all the steps explicit is essential to get a grasp of what the core business domain really consists of. In our case, we need to make sure to follow what the orc master currently does to keep his dungeon running. This can be done by either following him around, or making him walk us through his normal business process. We can't, however, rely on the business expert to explain the process to us in the necessary details. Also,we can't rely on our understanding of it to match what really needs to be done.

The main goal of this exercise, therefore, is to establish a baseline of understanding for what is going on and provide a shared language to talk about the problems, which will inadvertently arise. We are in an uncertain situation to start out with. This should not scare us, but we need to see it as the opportunity to increase our own understanding, as well as sometimes even the understanding of the currently executing person. Often business experts realize new details about their domain when questioning all the steps towards a goal, and they might even identify the possible problems.

In the case of implementing a business process, we can assume that the status quo is the least we need to replicate to replace the tools the business is currently using. So, first of all, we need to either rebuild or incorporate all the tools the business is currently using. We can later find the places where optimization makes sense and is possible when we get a firm grasp on the problem in general. We should also aim for gradual replacement of processes one by one instead of one big switch, as this minimizes the risk for the business.

When working with applications, it often is a problem to create a shared language between developers, product owners, as well as the business people in general. It is often stated that naming things is one of the hardest problems of computer science, and it is true that having a describing name makes many things easier. It is also often the case that a clearly named object is easier to extend because its scope is already defined by its name. Therefore, it is often discouraged in object-oriented design to name things with general words, such as Manager, Creator or Processor. When thinking about this problem in the context of our business domain, it becomes clear that we can, and should, reuse the established business language as often as possible. It all comes down to communication. We, as the developers, are new to the field, so the business experts introducing us will already have an established language to describe problems in the domain where we are missing them.

As we follow along the steps of our business expert, we should take the time to get accustomed to the specific language that is in use throughout. This becomes even more essential as we start writing code. We will constantly need to check in with the domain experts to take their understanding into account, so when we use the business language to encode the domain, it will be easier for us to talk to everybody around us to develop a better understanding of the domain. This is quite abstract, so let me give you an example. Consider this naming for the dungeon:

function Dungeon(cells) {
  this.freeCells = cells
}

Now consider we want to record changes in the amount of prisoners, and write the following code:

var dungeon = new Dungeon(100)
dungeon.freeCells -= 5
dungeon.freeCells += 3

Even though this is natural to a developer, it does not use any business-specific language. We need to explain the meaning of things like += to non-developers to make them understand the meaning. Consider on the other hand encoding the same logic in the following methods:

Dungeon.prototype.inPrison = function (number) {
  this.freeCells -= number
}

Dungeon.prototype.free = function (number) {
  this.freeCells += number
}

Using these methods to express the same thing, it looks vastly more domain - specific then before. We can now describe the problem in the context of the domain and the code looks as follows:

var dungeon = new Dungeon(100)
dungeon.inPrison(5)
dungeon.free(3)

It will now become quite clear, even to non-developers, what is going on and therefore we can focus on talking about if the behavior is correct rather than about the details of the code.

Considering the different ways to create a program, the main improvement that structured programming added to the way we program today is the idea that while working on a project, the programmer does not always have to have the whole project in his head to make sure to not duplicate functionality or interfere with the regular flow of the program. This is accomplished by encapsulating functionality in chunks to be reusable in other parts. Moving onward, object-oriented programming added the ability to further encapsulate functionality in objects, keeping data and functions together as one logical unit. One can say a similar thing for functional programming, which allows the programmer to think about his program as a flow of functions that are defined by their input and therefore can be composed as larger units. Domain-driven design now adds a layer on top, which adds abstractions to express business logic and can encapsulate it from the outside interaction. Creating a business layer that interacts with the outside world via a clearly defined API does this in this case.

Looking at these different practices, one thing shines through on all levels, and this is the idea of removing distractions. When working on a large codebase or on a complex problem, the more you have to keep in your head at once, the higher the level of distraction from the core problem. This is a major point of domain-driven design, and we are going to see how this plays out in the next chapter when we think about how we can go from a specification that we have seen before, toward a problem description we can continue to work with.

In a lot of cases, stating the problem is actually not obvious. This is why working towards a shared understanding between business experts and developers is so important, both sides need to agree on what they expect from a feature, or a piece of software. Allowing developers to state in clear terms to the business what the feature solves allows the developers to focus on the problem at hand and get input more directly. Similar to the principles of test-driven or behavior-driven development, stating in a clear fashion what something is intended to do helps the development a long way. At this stage, creating a route to get from A to be B as well as objectively stating when a goal has been reached, is what we seek. This by no means saves us from reconfirming that the goal is still the one to achieve constantly with the business, but it allows us to make this communication clear. With the language established, this now does not have to involve multiple hour-long meetings with no clear outcome.

With all this in mind, it is now time to dive into the essence of domain-driven design. Throughout this book, we are going to move our orc dungeon to the 21st century, allowing it to flexibly adjust to its business needs. As a first step, we are going to sit down and see what running this dungeon is all about and how our new software can add value using the concepts and the mindset of domain-driven design.