Introducing Jargon — TownPlan Driven Development

A Jargon TownPlan helps you quickly see how your domains are connected, and what their major resources are.

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 Town Plan can help stop this from happening. It shows where each of your Domains fit, and helps your consumers find what they need.

A picture is worth a thousand words - but an interactive visual is better.

Town Plans in Jargon are interactive. You can click on a Domain and see exactly which other Domains that it uses. After you have selected a Domain, you have quick-links to take you to the details page of that Domain.

Here’s an example of what that looks like:

Taking a closer look at a Domain in the Town Plan

There’s quite a lot of information on a town plan to digest. Let’s zoom in on one particular and talk about what’s happening here.

Firstly this is the ‘declaration’ domain, or at least that’s it’s alias. If you haven’t read it already, take a look at how Jargon manages releases and imports, as that’s how you give a Domain an alias when you import it.

Next we list a couple of Classes that this Domain has. We’ll touch on it a little later, but Jargon will choose these for you, or you can customise exactly which ones to show here.

Under the Classes, is where the API paths that this Domain exposes are displayed. We haven’t written a guide on it yet, but Jargon supports template-based, OpenAPI specification generation — more on that in future articles. Again, Jargon will choose these for you, or you can customise which ones are shown.

Down the side of the Domain, are the artefacts that this Domain has. Artefacts are different views of a Domain that help consumers use or better understand it.

This example Domain has

• a Vocabulary (the basic data model of a Domain)
• an OpenAPI Specification (which you can see on the domain details page)
• state lifecycle diagrams. We haven’t covered these off in a guide yet, but you can take a look at a sample one if you’re interested

The colours are important

Jargon Town Plans use colours for a few different purposes.

Firstly, the colour of each Domain conveys different information about the released status of the Domain.

• Yellow, means this Domain doesn’t exist, and is in the planning phase — more on this below when we discuss Town Plan Driven Development
• Green, means that this is the latest version of the Domain
• Blue, means that there is a newer version
• Pink, means that the newer version has breaking changes (which Jargon automatically detects for you when you release a domain)

Secondly, Jargon lets you group Domains together and the Town Plan will change the colour of the Domain’s background to show which group that it’s in. It will also create a legend in the upper-right corner to show you what each of the groups are.

Town Plan Driven Development

Ok, so we all now understand what a Town Plan is, and why we want one. But how do you actually create one?

Town Plans are actually just an artefact of a Domain, and unless you customise it, it’s completely derived from the structure and content of your Domain and it’s imports.

If you just go about your regular business of modelling data and importing Domains, your automatically created domain will look something like this:

A basic, autogenerated Town Plan. It shows each Domain, and links to the Domains that they Import.

On the left side of this screen however, is the editor that lets you customise and design the Town.

Let’s start by proposing a new Domain, that doesn’t exist in Jargon yet.

Here’s how to do it:

routing:transport
 classes:Route,Destination,Place
 apis:/route,/place

Let’s break that down.

routing:transport

Adds a new domain, with the alias ‘routing’ and adds it to the group called ‘transport’.

 classes:Route,Destination,Place

Lists Route, Destination and Place as the Classes you want to display for this Domain

 apis:/route,/place

Lists the API paths that you expect this Domain to expose.

As you type, the Town Plan will update to show your progress.

The Town Plan updates as you type

You can add as many proposed Domains as you like.

The order in which you list your new domains is what determines where they are placed on the Plan. It follows the same pattern as the numbers on a keypad:

If you want to skip over a place, type ‘_blank’ on it’s own line.

If you want to customise an existing Domain in the plan, follow the same steps as above, and be sure to exactly match the Domain you’re after to the alias in the editor.

Using those steps, you can quickly take the autogenerated Town Plan that Jargon gives you, and turn it into something much more useful, like this:

Wrapping up

So that’s Town Plan Driven Development in a nutshell. There’s a lot more to talk about in terms of the right way to go about planning, but that should be enough to get you started.

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