Context Mapping

Context Mapping is one of the most powerful and versatile tools from the Domain-Driven Design toolbox.

On the surface, it is just a drawing showing the relationships between different Bounded Contexts in a software development scenario. But Context Mapping requires asking in-depth questions and highlighting strategic information that will be vital for our project outcome.

When dealing with multiple models, a map becomes crucial for representing a clear separation of responsibilities between them and their cooperation. It becomes a key source of information for splitting teams’ ownership of models and minimising their coupling.

Eric Evans first described context maps in Domain-Driven Design: Tackling Complexity at the Heart of Software.

There, Context Maps weren’t intended to be heavyweight diagrams that constrain evolution, but rather quick sketches that guide teams in complex territory. However, the blue book only hinted at the power and versatility of Context Mapping. Field practice showed how they could be an incredibly versatile and powerful tool.

Greenfield vs Brownfield

A key distinction regarding the significance of context maps is their role in current software development initiatives. While a greenfield context map focuses on the ideal decomposition of a future system into collaborating models, a brownfield context map is more oriented towards reading the current forces constraining the collaboration between models in the present system.

This is no minor difference. Envisioning the future is a design exercise in clean modelling, driven by design principles. Reading the current status quo is a full-blown sociotechnical discovery initiative. A brownfield context map is one of the few tools to display the political forces acting on your software ecosystem.

Brownfield and Greenfield typically explore the relationships between many models surrounding our current area of interest. When the map area is limited to a collaboration between two contexts, it can be referred to as a local context map or a translation map.

---

Brownfield Context Mapping

The steps for drawing a context map differ significantly between greenfield and brownfield scenarios. Brownfield Context Mapping has a more straightforward recipe:

1. Detect models;
2. Make boundaries explicit;
3. Draw relationships between models;
4. Display the relationships’ direction (upstream/downstream);
5. Categorise the relationships;
6. Decorate the map with annotations about the risk areas or other meaningful extra info.

The following picture will be more explicit.

1. Detecting Models

Graphically, this is the most straightforward step: we simply need to record the models we detect during our investigation. Since we are dealing with a legacy implementation, some of the design drivers might be blurred. The original purpose of a model may have been obscured by years of patches and uncontrolled evolution.

However, a separate software component might be a clear indication of at least one independent model. Code ownership can be another interesting signal: different teams typically mean different models.

We shouldn’t aim for perfection at this stage. The reality won’t be clean, and our map must be honest. The following steps may give us more information.

2. Make boundaries explicit

Do we have a clean separation between our models? If yes, then we can draw a bubble around our model. Bounded Contexts, by definition, are the limit of applicability of a model, so sharp boundaries are somewhat required.

However, when dealing with legacy code, clean boundaries are usually a lucky exception. Most of the time, we will discover a lack of clear boundaries, and we’ll need a quick way to represent this mess. Clean boundaries can rely on the official representation, while more controversial interpretations can require a more explicit visualisation.

3. Draw relationships between models

Models are connected. They need to interact or to share information. Drawing a line between two bubbles indicates an ongoing relationship, such as an API call or a shared table in an old database.

The number of existing relationships can already be a warning signal: systems where every model is connected with everything else are really hard to maintain. The number of relationships is an indicator of potential ripple effects and the associated fear of modifying the code.

4. Visualise direction

Drawing relationships may look trivial at first. Models are connected, tables are shared, APIs are exposed. But a Brownfield Context Map shifts the exploration in a different direction. This way, it forces us to examine the collaboration between models and teams in a way that isn’t purely technical, but also political.

This mostly happens by focusing on the relationships between the models.

Upstream and downstream

The upstream and downstream labels show which side of the relationship has more influence over the other, constraining the available collaboration patterns.

For example, we’ll typically be downstream to external service providers, such as a payment gateway, which may not accommodate our requests for an additional field in their API. Here, we might choose to be Conformist in our first implementation and then upgrade to a safer Anti-Corruption Layer.

In other scenarios, we might be in a dominant upstream position, offering a standard entry point to our services without much room for customisation, maybe with an Open Host.

The upstream-downstream relationship captures the political relationship between the two models, not the technical one.

Emphasising Communication Bandwidth

Connectors between bounded contexts can convey extra information: thickness can represent the available communication bandwidth between two models.

Communication bandwidth is a scarce resource in many organisations, and a common source of friction and misunderstanding. It represents the available space for information exchange between the teams responsible for Bounded Contexts. It can be the time we reserve for meetings, cross-team coordination, and other tasks.

Two colocated teams could share modelling space and discuss topics in a simplified way without calling structured meetings. We can leverage this proximity to enable highly engaging collaboration patterns, such as Partnerships.

But two teams in different time zones, maybe part of other departments or—worse—companies, may not have any chance to build a shared mindset and foster continuous collaboration. With little available communication bandwidth, both teams would be better off with a clear definition of the boundaries and maybe writing more code to compensate for the missing conversation space.

While apparently discussing software models, we are taking a peek into organisational constraints.

5. Categorising relationships

A Brownfield Context Map focuses on the collaboration between models. This often mirrors the collaboration between the responsible teams.

After collecting information about the types of collaboration possible, we can attempt to categorise the kind of relationship between the models.

We need to keep in mind that we are examining the models in the making: we are looking at the forces that constrain their evolution, not at how the code behaves. It’s organisation boundaries and team collaboration, more than clean interfaces.

Collaboration patterns

Eric Evans describes some patterns that categorise these relationships.

• A Partnership describes a collaboration where two models can evolve harmoniously, as in the early days of a small company, where a single team can juggle with multiple models, or easily call a meeting for a joint modelling session with the other team.
• A Customer/Supplier describes a more structured co-dependency, where one side needs the other more than the other does. Collaboration is possible, but it requires coordination.
• In a Conformist, the downstream model adapts to the upstream one with minimal adjustment and trading flexibility for short-term development speed.
• An Anti-Corruption Layer will protect the downstream model from variations from the upstream one. This is particularly useful when integrating with third-party components.
• An Open Host highlights the different responsibilities that stem from the upstream role of being a service provider. This will mean more work on documentation, robustness and backward compatibility.
• A Shared Kernel highlights the need for robustness and expertise to maintain a shared model in which a small change can have massive ripple effects.
• Separate Ways describes the deliberate choice to move on with minimal integration between two distinct systems.
• Published Language refers to the use of a shared, official language for model-to-model communication, often allowing more parties to participate.
• The Big Ball of Mud describes the dynamics of a system that has lost its conceptual integrity and progressively became more challenging to change.

Visualising the sociotechnical complexity

These patterns describe different trade-offs in the sociotechnical stack.

An Anti-Corruption Layer implies writing more code to compensate for the team’s limited communication bandwidth. A Partnership goes in the opposite direction.

Similarly, an Open Host may be the more bureaucratic version of a Customer/Supplier, which became too demanding when more models started connecting.

Relationships between models result more from spontaneous evolution than a deliberate act of design. A Brownfield Context Map is typically a short-lived tactical tool to assess the current reality and highlight the most constraining concerns.

6. Decorate the map

If you’re aiming for perfection and clean diagrams, drawing a Browfield Context Map can be excruciating. Clarity, not beauty, is not the goal of the mapping effort.

But all the little inconsistencies, questions and doubts that haunted us while attempting to draw the map can find their way into our drawing. Warning signs, question marks, red notes, and any other necessary elements to convey the message can be added to the map.

The map is a tool to deliver a message. Make it speak!

How to use a Brownfield Context Map

Drawing a Brownfield Context Map is a detective job: it implies asking the right questions about the surroundings of our area of interest.

Ideally, when kicking off a new project, drawing a brownfield map should take less than an hour, provided we can obtain the necessary answers from the experts. Greenfield maps will take longer because different interpretations may clash, but we don’t need diplomacy in Brownfield; only transparency.

If obtaining answers about integrations and collaborations with other teams is challenging or inconclusive, we may have already gathered crucial information about the risks associated with a project.

“We should integrate with team X, but we couldn’t get any answers from anybody about how to perform this integration.”

The perfect storm may consist of fixed deadlines and unreliable external dependencies. A Brownfield Context Map helps detect these risks very early by forcing you to ask the right questions and meet the right people before committing to a hopeless death-march project.

---

Greenfield Context Mapping

Greenfield context mapping is a different sport. We need to detect domain hints that may signal the presence or the need for independent models. This would allow us to optimise models for their specific purpose.

A single-purpose model can be sharpened and distilled to excel at one thing, while trade-off models (such as those built on top of a shared database schema) tend to lose flexibility over time.

Unfortunately, while purpose is the most powerful force shaping our need for a dedicated model, it doesn’t provide immediate guidance for drawing our map. We can’t ask business stakeholders to provide us with a purpose with the sharp precision needed to define model boundaries.

Finding boundaries is a software architect’s job and can’t be delegated.

Detecting Bounded Context with EventStorming

Luckily, collaborative workshops like Big Picture EventStorming can provide valuable hints about partitioning a large enterprise model, especially when organised around a business flow.

• Different stakeholders, especially those from different offices, will have distinct needs; therefore, they will likely require separate models.
• Pivotal Events, which separate distinct phases, serve as natural landmarks between the model(s) to the left and the model(s) to the right.
• Swimlanes typically represent independent processes, often with a clear and specific purpose.

While none of these indicators is bulletproof, observing the emergent model and the people’s behaviour together provides incredible information about how to split a large enterprise model.

While a Big Picture EventStorming effectively detects domain signals, we must remember that Bounded Contexts are not a business concern.

Despite the invaluable contribution during the workshop, drawing the map with our business stakeholders isn’t always a good idea.

Going below the surface

Not every bounded context can be detected with signals from the business flow. Shared components may provide services or technical capabilities independently from the business flow. Often, logical layers are a better way to detect boundaries between models below the business flow surface.

Usually, we’d use a Local Context Map for that.

What about the collaboration patterns?

Collaboration patterns are somewhat premature when it comes to Greenfield Context Maps. The collaboration is not in place, and perhaps there is no organisation to investigate yet, and no organisational politics.

In general, collaboration patterns are a way to categorise existing collaborations, so we’ll need more field information to recognise them.

However, some relationships are easily recognisable even before the start, so it’s not uncommon to add Anti-Corruption Layers between our model and an external vendor. But when it comes to finding a distinction between a partnership and a customer-supplier before development is in place, then it could quickly become pointless.

---

Local Context Mapping

When working on the boundary between Bounded Contexts, concepts that may be part of different models require special attention.

This is where a Local Context Map may be helpful. It can visualise the current agreement and support the discussion when deciding which concepts belong to which model.

Cooperating models

In the following example, three models are cooperating in a space where the same data is used for different purposes. The emphasis on purpose helps preserve the integrity of the local model and provides a more robust foundation for future evolutions.

Refining the local Ubiquitous Language helps sharpen the model, keeping the involved Bounded Contexts sharp and clean. Interestingly, the same data can be seen with a different name (such as Balance and Liquidity in the example above) or lead to more precise concepts when translating the Due Date concept in Billing to the Expected Date in Forecast.

Stacked Models

Drawing the boundaries can become tricky in a layered model scenario, especially when the modellers trying to draw the line are also experts in the underlying layers.

In this example, we can see two models that are logically layered: a Content Design bounded context, working on top of a more generic Text Editing bounded context. The Content Design has a more sophisticated perspective on the content, allowing us to manage the different logical components of a piece of web content. The Text Editing model, on the other hand, is not aware of this sophistication and focuses solely on the editing experience.

The objection “At the end of the day, it’s all text” is valid and wrong at the same time. While everything can be text, and we’ll be using some text editing capabilities, designing content for the web happens at a different level of abstraction, with a more purpose-oriented semantic.

---

Applicability

Context Maps are a versatile tool, not strictly limited to Domain-Driven Design.

A Brownfield Context Map can be a very effective tool for capturing vital information about an initiative about to start. Moreover, the collaboration patterns can also be applied outside the software world, making the map a good tool for any transformation initiative.

A Greenfield Context Map is more of a design artefact for envisioning complex model collaboration, and then providing modelling guidelines for the future evolution of the model.

Local Context Maps can be vital when working on two adjacent models simultaneously. Their ability to navigate multiple perspectives and mental models can also be helpful in complex negotiation scenarios.