November Architect: Domain Model Structure - Part 2: Entities

Last month, we started a discussion around how to organize classes inside your domain model in a clear, easy-to-understand, and easy-to-maintain way. We reviewed our objectives and discussed why they are important. This month, we will start revealing a story of a business domain for the purposes of developing a software application. We will look into what is being managed in the domain day to day: Entities.

Discovering Entities

There are a number of technical definitions of an Entity that are popular in the industry. For example, here is a definition from Eric Evans' book Domain Driven Design, p. 89: An object that is not fundamentally defined by its attributes, but rather by a thread of continuity and identity.

The way I prefer to think about Entities is what we manage in our domain day after day. Entities span through long periods of time and run across multiple systems. They often have lives well beyond our applications and must be effectively tracked. As a general rule, assume that mistakes in Entity identification and tracking are expensive to notice and repair.

To discover Entities in your domain, talk to your functional people and end users. Ask them to walk you through scenarios the new system should implement. How are your users going to use your application? What is important to them and why? What do they really care about? What is important to your company and how does it need to be reported? The chances are you will be talking about what needs to be tracked and how, thus you will be talking about Entities.

Examples: Person, Account, Loan, Application, Payment.

Entity Relationships

What are the relationships between your Entities? Before getting into technical details, create a simple analysis diagram that shows the Entities you have discovered and their relationships. Lets consider a simple example:

Scenario 1: User logs in into the system to check the status of their applications and loans.

Scenario 2: User calls a Customer Service Representative (CSR) to reset their password.

Entity Relationship

Your research and conversations about the domain model revealed 4 Entities: Account, Person, Application, and Loan. Let us walk through the first scenario:

  1. User logs in into the system. The system needs to retrieve the user's security Account and verify their username, password, and any additional validation factors.
  2. Upon successful login, the system retrieves a previously stored Person record based on Account information. Thus, you see an arrow from Account to Person. You learned that each Account has a corresponding Person record, but not all People have created an online Account. That explains the numerical values on the diagram.
  3. Based on Person, the system retrieves their Application and Loan information. Thus, the arrows are shown from Person to Application and Loan. Person is created on the system with their first Application, but not all Applications are approved to become a Loan. Notice that there is no arrow between Application and Loan - we cannot determine its direction based on our current scenarios.
Now, let us take a look at the second scenario:
  1. User cannot verify the security information during login and calls CSR to reset their password. CSR asks them a series of Personal questions and retrieves their Person record.
  2. CSR retrieves the user's Account record for additional verification and resetting the password. Thus, you see an arrow from Person to Account.
Do not worry about having a circular dependency between Account and Person on the Analysis diagram. In one of our next articles, we will show several implementation options for the relationships. We will not have a circular dependency in the final implementation.

Domain Model Structure

Account, Person, Application, and Loan are our first classes in the Domain Model. For now, place them together in a sub-folder under the Domain Model root. We name this folder "Operation":

Domain Model Structure - Operation folder

Summary and Additional Tips

  1. Entity is an object that is not fundamentally defined by its attributes, but rather by a thread of continuity and identity.
  2. Entities span through time and space and are being tracked and managed in the day-to-day operations.
  3. Discover Entities by talking to your functional and end users. Create simple Analysis diagrams as a result of these conversations.
  4. Entity's primary responsibility is to maintain its continuity. Keep it simple by leaving complex behaviors out of its class definition.
  5. Managing life-cycle of Entities is a complex and risky job. Try to keep the number of Entities in the system down. Too many Entities will defuse your model and create no value.
  6. Compare Entities of the same type by their identity regardless of their form and history. Make identity type a Value Object.
  7. If you are interested in creating a simple base Entity class, you can start with the one listed below:

    ///<summary>Base Entity Class </summary>
    public class Entity <T>
        public T ID { get; protected set ; }
        public static T NewID { get { return default (T); } }

        ///<summary>Returns true if the object has not being stored in the system. </summary>
        public bool IsNew { get { return Equals(NewID, ID); } }
        public Entity(T id) { ID = id; }

Happy coding! To be continued...

Modelus Specification released!

Our new open source product went live this week: Modelus Specification. It is an implementation of a very powerful design pattern originally described in the Domain Driven Design book by Eric Evans as well as in this article by Eric Evans and Martin Fowler.

The library is written in C# using generic interfaces. The source code, binaries, and documentation are distributed under the Apache open source license, version 2.0. 

Give Modelus Specification library a try and check out our other open-source products. Let me know what you think or if you have any questions. Enjoy!

February book review: Domain Driven Design

Eric Evans
Domain Driven Design

I met Eric Evans in August of 2004, when his book had just came out and he was in Twin Cities at the Object Technology User Group (OTUG) talking about Ubiquitous Language, a language used by all team members to describe the domain model. I was very impressed with Eric's presentation. In very simple terms, he was able to find and explain the essence of what is often missing in domain implementations focused too much on technology.

You will not be disappointed with Eric's book. It describes patterns on how to explore a complex business domain and express it with a comprehensible software model. These patterns help me focus on central business problems while keeping the overall design of the systems understandable and manageable.

This is a must-read book for a business application designer and developer. Happy reading!

Welcome to ModelBlog

Thank you for visiting ModelBlog. We hope the time you spend with us will be both entertaining and worth your while. Have fun!