liveBook · Manning

Contract map

As explained in Clean Applications with Hexagonal Architecture

A diagram that shows an application’s neighboring systems and records the direction, intent, mode, and ownership of each interaction contract.

When an application has several neighbors, undocumented interactions make ownership and integration changes hard to see. A contract map makes those decisions visible before adapters are implemented. section 10.0

A contract map places the application at the center, its neighboring systems around it, and one line per interaction. It is neither a class diagram nor a deployment diagram. section 10.6

Record four decisions for each interaction:

  • Direction: whether the interaction is inbound or outbound. section 10.0
  • Intent: whether it is a request or a fact. section 10.6
  • Mode: how the interaction proceeds, such as a synchronous call or a longer-running process. section 10.0 section 10.7
  • Ownership: whether the application owns the contract or consumes another system’s contract. section 10.6

Partner CMS request

Record the CMS interaction as: Partner CMS → WriteFlow | inbound request | synchronous call | contract owned by WriteFlow. The CMS needs WriteFlow’s decision before continuing. section 10.6 section 10.0

Figure 10.3 Example of a potential external architecture as a contract map for WriteFlow. Every neighbor becomes one line that records a direction, a mode, and an owner. Draw your own the same way; the neighbors change, the four questions do not.

Use the example map to see how neighboring systems and interaction lines make direction, mode, and ownership visible. section 10.6

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Defines a diagram and its four recorded decisions, without specifying a formal notation.
Examples
Uses WriteFlow interactions with a partner CMS, identity service, publishing platform, newsletter, analytics service, and coordinator.
What you can do after
Build it from scratch by mapping each neighbor and recording four decisions per interaction before writing adapters.
How it connects
Connects hexagonal architecture with adapters, APIs, events, and synchronous calls.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Clean Applications with Hexagonal Architecture. The section links point to the parts of the book it draws on.