Enhancing Business Logic with PlantUML and EventStorming

Introduction

The complexity of software development is a well-acknowledged challenge within the industry. This complexity, inherent in the nature of software projects, necessitates considerable time and effort to manage effectively. However, time is often a scarce resource in fast-paced development environments, leading to inadequately managed software complexity. The consequences of this oversight are far-reaching, primarily affecting the quality, security, and evolutionary capability of software systems.

Nearly every software developer has encountered the daunting task of working on a codebase that is difficult to understand and maintain. These codebases often contain "spaghetti code" - a tangled mess of logic that is hard to unravel. Developers face inexplicable performance issues and live with the constant fear of introducing new bugs or breaking existing functionality with every change they make. This situation not only hampers productivity but also affects the overall health and sustainability of software projects.

Fortunately, the last two decades have witnessed significant progress in addressing the challenges posed by software complexity. Various approaches, initiatives, and experiments have been conducted to understand, mitigate, and prevent issues stemming from complexity. One of the pivotal shifts has been the adoption of the agile mindset, which emphasizes iterative development. This approach ensures that design activities are closely aligned with development cycles, allowing for faster and more responsive design decisions. Moreover, advancements in software design, particularly through the adoption of Domain-Driven Design (DDD), Command Query Responsibility Segregation (CQRS), and the Port/Adapter Architecture, have contributed to a more mature understanding of how to structure and manage complex systems. These methodologies have introduced robust building blocks that facilitate clearer thinking and more effective design strategies, exemplified by techniques like EventStorming.

Another significant development has been the rise of the *-as-code initiative, which treats design artifacts with the same rigor as code. This approach, exemplified by tools like PlantUML, enables automation processes such as build, validation, and distribution to be applied to design resources, thereby enhancing collaboration and efficiency.

This introduction sets the stage for discussing how modern software development practices and tools have evolved to tackle the challenges of complexity. By embracing agile principles, advanced design methodologies, and automation, the software development community continues to make strides toward creating more manageable, high-quality software systems.

Start is Easy

Embarking on the journey to simplify the implementation of business logic in software projects may seem daunting at first. However, with the right tools and methodologies, this process becomes much more approachable and effective. Two pivotal resources in this endeavor are PlantUML and EventStorming, especially when utilized in conjunction with the tmorin/plantuml-libs library.

EventStorming

EventStorming stands out as a powerful, collaborative workshop format that brings together different domain experts to discover, explore, and model a domain. It uses a visual and interactive approach, employing sticky notes to represent domain events, commands, aggregates, and other key concepts on a large wall. This method is particularly effective for:

• Introducing clarity in design: By visualizing complex business processes and domain logic, EventStorming helps teams understand and navigate the intricacies of their domain, leading to clearer and more effective design decisions.
• Fostering collaboration: It encourages active participation from all stakeholders, including developers, business experts, and product owners, ensuring a shared understanding of the system and its goals.

PlantUML

PlantUML complements EventStorming by providing a tool to precisely document the insights and designs conceived during brainstorming sessions. It is a textual tool that allows for the generation of UML diagrams from a simple and intuitive Domain-Specific Language (DSL). Its benefits include:

• Code-like management of design resources: With its *-as-code approach, PlantUML enables version control, collaboration, and automation of design artifacts, much like software code.
• Automation of design processes: The ability to apply version control, review processes, and automated validation to UML diagrams ensures consistency, quality, and adherence to design principles.

tmorin/plantuml-libs

The tmorin/plantuml-libs library is a treasure trove of PlantUML components, offering ready-to-use elements for a variety of design needs, including EventStorming building blocks. This library significantly simplifies the process of documenting and sharing complex design ideas by providing:

• Comprehensive design components: From cloud architecture to EventStorming, tmorin/plantuml-libs offers an extensive range of components that cater to diverse design activities, enabling detailed and precise modeling.
• Seamless integration with EventStorming: The library's components dedicated to EventStorming ensure that the transition from collaborative brainstorming to formalized design documentation is smooth and lossless.

By leveraging EventStorming for collaborative discovery and modeling, PlantUML for precise documentation, and tmorin/plantuml-libs for a rich set of design components, teams can significantly improve the implementation of business logic in their software projects. This synergy not only enhances the clarity and quality of design but also fosters a culture of collaboration and continuous improvement.

The Example: Designing a Note-Taking Application

The journey from abstract concepts to concrete implementation becomes clearer when illustrated through a practical example. In this case, the design and development of a note-taking application serve as an ideal scenario to demonstrate how PlantUML and EventStorming, powered by the tmorin/plantuml-libs library, can significantly improve the implementation of business logic.

This example focuses on a subset of the business logic integral to a note-taking application - specifically, the creation of a note. It aims to showcase a step-by-step design process, from initial conception to detailed implementation, illustrating the application of EventStorming and PlantUML in real-world scenarios.

The Aggregate design

The design activity typically commences with a trigger, which, in this instance, is the CreateNote command. This command symbolizes an action initiated by something or someone to create a new note within the application. It involves several critical components:

• Command Execution: Tied to an aggregate instance, the execution of a command results in a set of domain events that describe the necessary changes to the aggregate or denote a failure due to business rule violations. This process excludes the handling of the persistence layer, focusing solely on the business logic.
• Aggregate Definition: An aggregate represents a business concept, complete with an identifier and state, and undergoes a lifecycle of creation, update, and deletion. The management of an aggregate's state typically employs the Repository pattern from Domain-Driven Design.

The CreateNote command's execution leads to a sequence of actions:

1. Creation of the Note Aggregate: Initiation of the note's lifecycle.
2. Production of the NoteCreated Domain Event: Signifies the successful creation of the note.
3. Application of the NoteCreated Domain Event: Updates the state of the Note aggregate accordingly.

These steps are encapsulated within a single transaction, ensuring atomicity and consistency.

The initial design of the CreateNote command is succinctly represented in a PlantUML diagram, incorporating elements from the EventStorming package of the tmorin/plantuml-libs library.

The previous diagram is based on the following PlantUML snippet:

@startuml
' inclusions <1>
!include https://raw.githubusercontent.com/tmorin/plantuml-libs/v13.0.0/distribution/eventstorming/single.puml

' declarations <2>
Command("CreateNote")
Aggregate("Note")
DomainEvent("NoteCreated")

' associations <3>
CreateNote -> Note : creates
CreateNote --> NoteCreated : produces
NoteCreated -u-> Note : applied to
@enduml

1. The statement loads the eventstorming package of the library tmorin/plantuml-libs.
2. The statements declare the artifacts based on the building blocks of the EventStorming.
3. The statements associate the artifacts.

This diagram outlines the core components involved in the command's execution, including:

• A data structure defining the CreateNote command.
• A data structure representing the Note aggregate.
• A data structure for the NoteCreated domain event.
• Behaviors associated with the aggregate to produce and apply the domain event based on the command.

This design clarity is achieved through the strategic use of EventStorming building blocks, enabling a concise representation of the command's workflow and interactions.

Handling of the API

In practical applications, commands related to an Aggregate often require a more user-friendly interface for API exposure. This necessity introduces the concept of a Facade Command, which serves as an intermediary, transforming user actions (e.g., form submissions) into system commands. In our example, the SubmitNewNote command acts as this facade, facilitating the submission process through a user interface, with the end user as the initiator.

The previous diagram is based on the following PlantUML snippet:

@startuml
' inclusions <1>
!include https://raw.githubusercontent.com/tmorin/plantuml-libs/v13.0.0/distribution/eventstorming/single.puml

' declarations <2>
Person("EndUser")
UserInterface("SubmitNoteForm")
FacadeCommand("SubmitNewNote")
Command("CreateNote")
Aggregate("Note")
DomainEvent("NoteCreated")
EndUser --> SubmitNoteForm : uses

' associations <3>
SubmitNoteForm --> SubmitNewNote : executes
SubmitNewNote --> CreateNote : executes
CreateNote -> Note : creates
CreateNote --> NoteCreated : produces
NoteCreated -u-> Note : applied to
@enduml

1. The statement to load the eventstorming package of the library tmorin/plantuml-libs does not change.
2. The statements to declare the artifacts has been updated to include the Command Facade, the User Interface and the End User.
3. The statements to associate the artifacts has been updated to include the new associations.

The implementation of business logic, as demonstrated again, adheres to principles of clarity and conciseness. The design introduces a well-defined data structure for the facade command, complemented by behaviors specifically tailored to generate the command.

Although the focus of this article is primarily on the intricacies of business logic, leaving user interface interactions less explored, the facade command is structured in a manner akin to a REST API endpoint. This approach, leveraging a handful of EventStorming's foundational building blocks, ensures that the separation of concerns within the system's architecture is both apparent and efficiently managed.

Extending the Example

While this example primarily focuses on the creation of a note, the methodology and tools demonstrated can be applied to a broader range of commands and queries within the application. Additionally, this approach can be extended to handle reactions to domain events, further enriching the application's business logic and its responsiveness to user actions.

Conclusion

In the journey to master the complexities of software development, especially in implementing intricate business logic, the combination of PlantUML and EventStorming has emerged as a beacon of innovation and efficiency. This article has demonstrated, through practical examples and theoretical insights, how these tools, underpinned by the tmorin/plantuml-libs library, offer a robust framework for designing and documenting software systems.

Understanding the core principles of Domain-Driven Design (DDD), Command Query Responsibility Segregation (CQRS), and the Port/Adapter Architecture is crucial for any software development endeavor. These methodologies provide a structured approach to managing complexity, ensuring that the business logic is both scalable and maintainable. PlantUML and EventStorming, in concert with these design principles, enable teams to visualize and iterate on complex workflows and domain models effectively, fostering a collaborative environment that bridges the gap between technical and non-technical stakeholders.

The tmorin/plantuml-libs library serves as an invaluable resource, offering a wide array of components that streamline the design process. By utilizing these components, developers can quickly prototype and refine business logic, ensuring that the final implementation is aligned with the domain's needs and constraints. Moreover, the *-as-code approach advocated by these tools facilitates automation, version control, and continuous integration/continuous deployment (CI/CD) practices, further enhancing the development workflow.

Through the example of designing a note-taking application, we've seen how EventStorming and PlantUML can be applied to real-world scenarios, allowing for a clear and concise implementation of business logic. This approach not only simplifies the initial design process but also ensures that subsequent modifications and extensions can be made efficiently, without losing sight of the overall system architecture.

In conclusion, the synergy between PlantUML, EventStorming, and the tmorin/plantuml-libs library provides a powerful toolkit for tackling the inherent challenges of software complexity. By embracing these tools and methodologies, development teams can improve the quality, security, and evolutionary capabilities of their software products. As the field of software development continues to evolve, leveraging these advanced design and documentation practices will be paramount in creating systems that are both robust and adaptable to changing business needs.