In order to best deliver a software product, software developers who follow the Domain-Driven Design paradigm work to model the client organization’s operations. To achieve a sufficiently rich model, DDD developers use the best technique yet devised for complex coordination: human language. In conversations held to glean the client’s domain knowledge, participants generate what DDD author Eric Evans coins the system’s ubiquitous language: a vocabulary akin to a subculture. This shared understanding of the domain between owner and developer bounds the system’s ultimate success.

A breakthrough in explanatory simplicity

The Event Modeling methodology pioneered by Adam Dymitruk works within this paradigm. Since the essence of a work organization is a body where things get done, event modeling’s foundational item is the event itself, ie, each thing that is done.

Practitioners of the methodology transform domain knowledge into system architecture by generating a series of left-to-right timelines, usually on a whiteboard, organizing events into a depiction of a process. The canonical example is a hotel booking system.

At the top of each left-to-right step are wireframes for UI elements. These are distributed vertically among types of user into swimlanes (eg “Manager” and “Guest”) and point down to blue notes in the middle row. Blue notes are commands (eg, “Add room”). These in turn point down to orange notes for events (eg “Room Added”), which then point back up to the middle row of the next step, which contains green notes representing multi-entry views. These in turn lead back up to the next step’s UI or to an external system, as represented by a gear icon.

Unlike in BPMN and other flow notations, branching is deliberately omitted—each model tells one linear story—so that the single left-to-right line echoes written language itself, making the diagram easy to discuss.

Be the ball

But a model is not a simile situated a step away from the domain; it is a metaphor, a stand-in for the domain, and as such we can approach a step closer than tracking events. Rather than noting where the ball landed, we can, as Ty imparts to Danny on the golf course in Caddyshack, be the ball.

Being the ball rather than tracking it means making the foundational primitive not the event—the record of what has happened—but the action: the description of who can do what. It means that the organization is not a place where things have been done, but where people (and now with AI other types of agents) do things.

Event modeling’s atomic items—a Book Room command and Room Booked event (perfective nominalizations)—must be placed within a diagram or a Given-When-Then verbal construct in order to be understood. Role & port modeling’s atomic item is, in contrast, an operation expressed as a natural sentence: “A Guest can book a Room—provided that room has Availability on that date,” which sounds like how the business owner might describe the requirement during a discovery meeting. Role & port modeling hews more closely to the system’s ubiquitous language and develops it further.

The grammar of action

The fact is, in event modeling the user is downgraded; she appears on the timeline but doesn’t get a color, nor makes it into the Given-When-Then sentence structure. This is a forgetting of what we learn in school: that a good and clear sentence is an active one, requiring a clear subject (the agent) as well as a verb (the action) and an object (the thing acted upon).

As we also learn in school, the way to flesh out an occurrence is to ask the Five Ws: Who, Where, What, Why, and When. Here we will add another two: Which and Whether. In the context of an organization-managing software system, with the related collection in parentheses:

• Who: The user or agent performing the action, eg, a Customer of the Hotel Chain (Roles) [required]
• What: The action being performed, eg, Reserve (Actions) [required]
• When: The current status of the item being acted on, eg, Available (Statuses) [required]
• Which: The item being acted on, eg Room Night ([Item Collection, ie, Room Nights]) [required]
• Where: The interface via which the operation is performed (Ports) [optional, as these may emerge from the user’s list of available interfaces]
• Whether (ie, if): The conditions under which the operation can occur [optional, as its status may be a sufficient condition]
• Why (ie, as part of): The process(es) to which this operation contributes (Processes) [secondary, but required for diagramming and contributes to tracking]

Looking at each of these more closely:

Who: The org chart

Like an adventurer donning a costume, the user takes on a role, assuming a position within an organizational body.

Everything that happens in the system—every update and state change of an entry, ie, mutation—is triggered by users (aside from systems with a subset of passive mutations triggered by environmental conditions).

Whereas most architectures directly assign a user to a single group, in role & port modeling we introduce several dimensions to the relationship between users and the operations they perform, thereby achieving the necessary expressiveness most systems lack.

Operations are assigned not to users nor even to Groups, as is standard in most mature systems, but to Positions, which is a better model of organizations.

To provide access to the interfaces where these operations are performed, Positions are also assigned ports, consoles, domains (the organization’s various areas of activity) and optionally subsystems.

A first added dimension is that the user is not assigned a position; instead, the user assumes one or more roles, and it is the role that in turn gets the position.

A second dimension is that the role constitutes a position at a body, which may either be the root organization or a child one.

Positions and bodies are both hierarchical, enabling them to encompass others, adding more dimensions to the expressiveness of user roles.

If subsystems are in place, the user cannot access their role if logged in to a subsystem lacking the role’s position.  

Contrasted with event modeling, role & port modeling restores the rightful primary place of users; after all, without the user an operations system for an organization is inert, and without a complete perspective on users, the system design as a whole is incomplete; developers would need to handle users eventually without the benefit of integrated structured specifications.

What: The things we’ll do

[this section under development]

When: The current state

[this section under development]

Which: All the nouns in our world

The item belongs to a collection and always has a status / is in a state. A mutation changes that state. Actions trigger mutations, unless the mutation is set up as for attestations, where multiple actions of this mutations are required to have happened before the mutation is triggered.

[this section under development]

Where: True yin 

Interfaces are where the action happens.

A complete system design needs more than the active, mutating part. It needs the receptive, navigational, interface part: how people are conducted to their work and where they perform it.

Whereas event modeling views navigation and interface as aspects of and contributories to events, role & port modeling views them from the perspective of positions—and only optionally as aspects of activities.

The interface library has two primitives: the Console, a multi-entry table view for navigating to items (corresponding to the green note in event modeling); and the Port, a detail view for working on a single item (the wireframe in event modeling). Consoles serves to conduct a person to their work at various Ports. And Consoles can in turn be embedded within Ports, with the option of a checkbox rather than conduit interface to reach the further embedded Port, which appears in drawer form.

(This concept of a port differs from that in Alistair Cockburn’s Hexagonal (Ports & Adapters) Architecture. Whereas in hexagonal architecture the port is a thin boundary and business logic lives in the system’s core, in role & port modeling there is no core; instead the port expresses the receptive side of the business logic, while the user’s operations express the active side; business logic happens when the two engage. Having business logic be a product of operations and ports, both of which are configurable, rather than nestled in a core, means that the software is far more easily modified and developed; it is softer software.)

A user’s access to a particular interface is generated by an amalgam of settings. First they must be navigation to it. This covers from within a console on a role dashboard in the form of a conduit link to a port concerned with a particular collection entry is displayed when:

A) The target Port is assigned to both the Console and to at least one of the user’s Role’s Positions (the Position dimension)

B) The entry in the Port’s Collection belongs to a Body to which the user's relevant Role also belongs (the Body dimension)

C) The entry in the Port’s Collection has a Status referred to in an Operation assigned to the Position (the Status dimension)

D) The operation is agnostic about which Port performs it or specifies this one (the Port dimension)

It is expected that the Status dimension will frequently come and go as an entry’s status changes aa operations are performed on it. When that happens, the conduit vanishes—perhaps to reappear in someone else's workflow based on their Position's assigned Operations. Indeed, such changes constitute the system’s value.

Whether: Conditions to allow an action to occur

Beyond an item's status exist any number of filters blocking action. These might be values of fields within the item, or of one or more other items whether of the same collection or not. They may be environmental variables or conditions read from external systems.

It is in the plethora of detail here that complex, real-world systems can be developed.

Why: Coalesce into process

Once actions have been articulated, they are arranged into ordered lists, coalescing into processes. In role & port modeling then, a process is a set of operations and the interfaces required to perform them, the workflow set by the mutations of the constituent operations.

Get StereoVision

One clear advantage of event modeling is that it provides an instant visual overview of a process using a whiteboard and post-its, whereas role & port modeling displays a process merely as an ordered list, which is a less easily grasped overview.

But because operations carry richer data—the full sentence—a software engine can receive this list, definitively sort it by following the direction of travel in the mutations, and output on the fly both a BPMN diagram of the process (a branching structure, decision points, roles) and an event model timeline (a single path through time). Until now it has been unusual for a software project to have both BPMN and event modeling diagrams, but role & port modeling accompanied by suitable software provides both diagrams automatically, like diagrammatic double-bookkeeping.

The convention for naming processes is the item, the nounification of the action done to it, and the recipient, eg, Treasure Restoration for Customer. This differentiates it from operations, which are described more directly with the verb, and includes the recipient in the spirit of being customer-focused, of being service-oriented, even if the recipient is internal.

Operation Operation

All the primitives just discussed except the Position and the Process comprise the Operation. Its required fields are Action, Collection and Status; optional fields are Port and Conditions. The Position and the Process then get this Operation and any number of others.

This is represented in the diagram by the gap between Who and Why and the other four questions (“whether” being an aspect of the Operation).

Abracadabra

DDD asks us to model the domain in human language. Event modeling responds with a breakthrough in visual simplicity. But in the quest for that simplicity, it sacrifices the primacy of the subject—the person doing the work, the user. When the user is a swimlane label rather than a formal primitive, the simplicity that was gained in the diagram must be rebuilt as complexity elsewhere: in code, in separate coordination layers, in governance mechanisms added after the fact. To paraphrase Ty Webb, a donut with no role is a Danish.

We already have a time-tested structure for modeling events and operations: the full sentence. Whereas in most formal systems adding detail muddies comprehension, expressing operations as sentences can sharpen it; the linguistic sentence can be a formally precise description while remaining the most humanly graspable one. True, we need some computer help in sorting these sentences into visual overviews. But we are better at sentences—even long windy ones with detours through Ports hither and thither—than we are at most anything else.

With the advent of LLMs, the same can be said now for AI: role & port modeling is the way to describe the organization to AI and to govern AI in the organization.