Documenting Your Event Driven Architecture in 5 Steps

As organizations look to adopt an event-driven architecture, they might find difficulty in documenting the design process, understanding how changes might impact services, and how to verify that the runtime matches the intended design. In this blog post, I’ll look at the step-by-step process on how to document your event-driven architecture to better understand how events move through your enterprise.

Benefits of Event Driven Architecture

Event-driven architecture provides an asynchronous communication layer that enables organizations to develop new applications faster. Applications communicate in a publish-subscribe manner, making it easier to scale the deployment, add new innovations and react faster to business requirements. Some of the key benefits of event-driven architecture are:

• Asynchronous communication
• Loose coupling of applications
• Scalability
• Routing of data
• Persistence

Challenges of Event Driven Architecture

As you scale your event-driven architecture, it becomes increasingly difficult to keep track of where the data is routed to, which applications are publishing events, and which are consuming. Because of its decoupled nature, there is no simple way to identify the correlations between these various components. You may start asking questions like:

• If I change the event payload format, what are the downstream applications affected by the change?
• As a developer that needs a specific set of data, what does my application need to subscribe to?
• What data is currently available to my application?
• How can I reduce development time of my application with code generation?

Why You Need Event Management

Spreadsheets, PowerPoints, Visio diagrams, and various other techniques have been implemented to try and solve these challenges, however none were developed with event-driven architecture in mind. A tool built to accommodate fast-paced and ever-changing requirements would provide more insight for your organization.

Adopting event management as a practice in your organization will solve the challenges of event-driven architecture by easing the design, development, and onboarding of new innovations. So, what should be included in the ideal event management tool?

Understanding the Concept of an Event Portal – An API Portal for EventsAn event portal, like an API portal, provides a single place for an enterprise to design, create, discover, share, secure, manage, and visualize events.Learn more

An event management tool should be a single place for architects and developers to collaborate and document the various events routed throughout the organization. There should be a representation of applications, events, and the payload formats for those various events.

It should also provide relationship mappings of these various objects and provide an interface for discovering them. One such tool the industry has been adopting is referred to as an “event portal”.

Organizations embracing EDA for enterprise integration find value in an event user portal where consumers of events can discover events and request access to subscribe to them.” ¹

How to Document Your Event-Driven Architecture in 5 Steps

The key components of event-driven architecture are applications, routable information, the format of the data, and one or more event brokers. Here are the 5 steps you need to follow to properly document your event-driven architecture and realize the full benefits of this pattern.

1.      Identify Your Events

The first step for designing your event-driven architecture is identifying the events; this could be a new order event, a temperature sensor threshold event, a stock ticker update, etc. An event is a change in state that must be acted upon, and the event may contain information within it to describe the change in more detail.

2.      Pull Routable Information from Events

Once identified, the key routable information should be pulled from those events. This is information that might be used to describe or filter the event and can be found in the contents of the event or can be defined based on application requirements:

• What is the status of this order?
• Is this new order from a physical store or online store?
• In what location was the order placed?
• What is the unique identifier for this order?
• What is the shipping address for this order?

I recommend that you organize your routable information into a topic. A topic describes the event and provides consumers of the data with the ability to filter based on these attributes.

Topic Hierarchy and Topic Architecture Best PracticesThe best practices in creating a sound event topic hierarchy that lets applications identify, attract, and consume the events they need.Learn more

You may also identify the routable information from the data within the event. For example, a new order event might have a unique ID, shipping address, billing address, and a list of products in the payload itself. This data should be represented in the event management layer for documentation purposes, and to help better discover events later that contain specific keywords.

3.      Document Events in Your Event Management Tool

Your events should be documented in your event management tool, like an event portal, with their associated topic and payload format. If you’re a developer, mapping these relationships will help you find the data your application requires. If you’re an architect, it’ll help you understand the impact of making a change to an event.

4.      Identify Your Applications

Once your events are designed, the applications can be identified. The applications can be documented in the event management tool to identify the owner, the language & protocols, and the events they are publishing and/or consuming.

5.      Visualize Relationships Between Components

Once the components are documented, the relationships between them should be visible. An event management tool with a graphical format, for example, can help architects understand the flow of events and how changes will impact various applications and processes. In addition to visualization, the various objects should be searchable to allow developers an easy method of finding the data they require, like a searchable catalog or menu.

Automating Event Discovery to Document Older Deployments

You may be thinking “I already have hundreds of applications & events deployed in an event-driven manner, I don’t have the time to manually document all these objects!” For initial documentation, an ideal event management tool should provide a way of automating the discovery of events and applications. This would allow you to populate a catalog and visualize the relationships without the manual effort.

A discovery scan should also allow you to compare your runtime against your design time. This is particularly helpful if you have designed your event-driven architecture and want to verify that what has been deployed matches your design. This can be used for validation of configurations, auditing, governance, and iterating on the deployment.

8 More Ways PubSub+ Event Portal can Make it Easier to Manage your Event-Driven ArchitectureEight impactful things you can do with PubSub+ Event Portal as you implement event-driven architecture across your enterprise.Read now

Benefits of Documenting Your Event Driven Architecture

Now that you have your event-driven architecture documented, you have a centralized source of truth for how events move throughout the various systems in your enterprise.

These are some of the benefits you should take advantage of:

• Architects can understand which applications are more closely related and how changes might impact downstream applications.
• At design time, prioritize which applications and events are required now and which can be developed or integrated later.
• The searchable catalog provides an interface for developers to get the data they require, which topic to subscribe to, and what format the payload is expected to be in – this information can be exposed to internal and even external consumers of data via event API products to create a ‘Data as a Service’ offering.
• At development time, use AsyncAPI for code generation so you can focus on the business logic instead of focusing on the broker connectivity details.

If you found this post useful, visit the PubSub+ Event Portal page for more information on how Solace approaches event management. Or, if you want to get hands-on with PubSub+ Event Portal, you can sign up for a free trial.

¹Source: Forrester Research “Use Event-Driven Architecture In Your Quest For Modern Applications”, Apr 9 2021, David Mooter