Solving Architectural Entropy With Runnable Diagrams

“Software architecture does not age gracefully. Software architecture degrades in direct proportion to the number of changes made to the software” - Architecture of Open Source Applications, Berkley DB.

This observation is painfully familiar to anyone building domain-driven systems at scale. We often begin with carefully designed microservices and a shared understanding of the domain, but as new requirements arrive, teams optimize for delivery speed and as a result, architectural shortcuts creep in. Over time, the original design intent fades and it becomes increasingly difficult to understand how it all works.

In a typical engineering discussion, complex ideas are explained using diagrams and visual cues. Architectural diagrams are a central component in today’s engineers’ arsenal because of this universal appeal – whether it be a new joiner or the veteran, diagrams provide instant clarity that code alone cannot.

Unfortunately, most diagrams fall out of date as the system changes. But what if diagrams were not a documentation of a past version of the system, but were the definition of it?

Instead of merely describing interactions between microservices, Business Process Model and Notation (BPMN) uses a visual language for defining how microservices interact with one another to solve business requirements. The same diagram is understood by humans and executed by machines, creating a powerful synergy between architecture, implementation, and business intent.

By introducing an explicit orchestration layer, BPMN brings proven composition patterns. Instead of bespoke in-house implementations, a unified orchestration layer prevents domain driven services from drifting from their original design intent.

With executable diagrams, we can finally tame the problem of architectural entropy that slowly creeps in, even in well intended design. It makes the system easier to understand and faster to evolve, while bringing different factions of the organization closer.