A worked example of using Jargon for Domain Driven Design — Part 2

Welcome to Part 2 of using Jargon for Domain Driven Design.

In this article, we will create a Town Plan from the conceptual model in Part 1. That will give us a roadmap of the Domains we need to create and a place to visualise and mange how the Domains are evolving over time.

Background: What is a Town Plan?

As you and your team create and release more and more Domains, it gets harder and harder to keep on top of everything. Different teams will start using different versions of things, and your carefully architected vision for a suite of Domains will quickly devolve into a big ball of mud.

A Jargon Town Plan can help stop this from happening. It shows where each of your Domains fit, and helps your consumers find what they need.

Check out our story on Town Plan Driven Development if you would like to know more.

Let’s start at the end, and work backwards

Here is what our Town Plan is going to look like when we’re done:

Jargon’s flat, non-interactive, representation of a Town Plan — perfect for sharing with others.

Ok, let’s break this down a little before going through the steps to create it.

It’s got four boxes, each one corresponding to the Domains that we identified in Part 1: Sales, Marketing, Warehouse & Shipping.

Each Domain has a list of:

• Classes (Pricing, Invoice),
• Basic API paths we envision that they will offer (/products/{id}, /track/{id}), and
• Names of business events we expect them to fire ( cart.update, shipment.shipped)

The Town Plan isn’t meant to be the authoritative source for this information, and it only displays a few items in each list to help consumers understand what each Domain is for. The interactive view has links to each of the Domains where consumers can find out everything they ever wanted to know about the Domains on your Town Plan.

Each of the boxes is the same yellowy-beige colour — that’s important. That colour indicates that these are all proposed Domains. As they get implemented and evolve over time, their colours will change to represent the stage of life they are in that gives you an at-a-glance view of the current state of your system:

• Published,
• Oudated by a new version that has non-breaking changes,
• Outdated by a new version that has breaking changes,
• Deprecated

There are also two background colours on this Town Plan, blue and red. These colours indicate a grouping of Domains. The specific colours here aren’t important, and the interactive view has a legend you can use to see what each of the colours mean.

Speaking of the interactive view:

Creating the Town Plan

Ok, let’s work from the ground up to build that Town Plan.

A blank Town Plan isn’t very interesting, so here’s one that’s already got the Sales Domain:

Jargon’s Town Plan interactive view has an isometric view that’s more detailed than the flat representation.

Because we’re designing these Domains, we’ve got to describe them to Jargon and create placeholders. Once we’ve created them, then the Town Plan will source these details from the actual Domains.

You can see that we’ve given the Sales domain:

• a name: Sales
• a description: The Sales Domain helps…
• Classes, APIs and Events.

Lets add the other 3, and group them into business areas:

Here you can see the legend for the Domain grouping, and how each of the Domains has been marked up to indicate which group it belongs to. Grouping Domains like this isn’t required, but it helps to convey the proximity and collaboration of Domains.

Ok so far, so good, but we can add just a little bit more information to our proposed Domains to set us up for success when designing them — we can design how they interact with each other.

Designing for cohesion and coupling

From our conceptual model, we know that the Marketing Domain is the authoritative source for creating Products and assigning them with an ID.

It’s reasonable then to show these kinds of relationships on the Town Plan:

Domains have relationships to others. Here, a Green line indicates cohesion via classes or properties being referenced. Orange lines indicate coupling, such as directly calling a Domain’s API.

Clicking on the Sales Domain shows linkages, either cohesive or coupled, to other Domains.

The Town Plan is a bit too high-level to show the details of these relationships, and we’ll see how Jargon models them in the next article, where we design the Marketing and Sales Domains.

Wrapping up:

That’s where we’ll end this entry, with a Town Plan that has four proposed Domains.

The Town Plan for this article is available in the public Jargon instance.

Next time, we will implement the Designs for two of these Domains, Marketing and Sales.

If there is anything else you really need to know before the next article comes out, you can:

• check the Getting Started Guide
• leave a comment below
• raise an issue at the jargon issue tracker GitHub repository
• Sign up for a free Jargon account and create your own conceptual model