Part I. Toward a shared modeling grammar

I can clearly remember when I first faced with a corporate software project.

Unlike my previous development experiences, the business was so complex that I wasn’t able to grasp it. I carefully read the project’s documentation, but still I wasn’t able to truly understand the application. Most of the documentation was about financial assets, cash flow management, fund switches, bank’s commissions. Nothing about databases or tiers, just a few informations about an old order routing system.

I felt lost. I was missing the overall vision.

A simple overall vision is the foundation of any architecture.

When we got the first frustrations due to misunderstandings between the customer and the team, I realized that we didn’t speak the same language. Indeed, we had high level functional specifications, written by lawyers and financial experts that gave a lot for granted while leaving aside many edge cases.

Understanding the problem, led to the solution: we revised the concept of "ubiquitous language" and we switched to a truly domain driven approach.

We are talking about a project that took four years to complete. Three teams of five people worked hard on the different modules of the application (CRM, portfolio management, advisory and so). As you can guess, we had different changes of specifications over time, becouse the consultants had lots of second thoughts about the customer’s business processes.

The Epic's vision

Despite the initial panic and errors done, we built a powerful application that seamless handles many different contexts each with complex business rules.

Such a good result derived from these high-skilled teams, a bunch of smart people who daily shared (and discussed) their own experiences.

We had our vision: the domain model was the heart of our application, the asset to protect and to depend upon.

Going beyond the initial knowledge base, we developed a set of patterns that help us to design and implement the ubiquitous language in a predictable amount of time. The patterns worked like a shared modeling grammar so that all modelers were able to catch the intents of the others.

This led us to a sort of domain-driven software factory, with a fast and predicible production line.

Of course, the real challenge is to actually find an incisive model, one that captures subtle concerns of the domain experts and can be expressed in the code. Ultimately, we hope to develop a model that captures a deep understanding of the domain. This should make the software more in tune with the way the domain experts think and more responsive to the user’s needs.

This part of the manual describe a set of rules, patterns and best practices that we have found useful to get such result. Some conventions are designed to ease the comunications toward the model’s code, other to easily embrace the change or to increase team’s productivity.