Architecture diagrams are a wonder. They help create a shared understanding about application architecture, business processes, and data flows between you and the stakeholders of your app.

Around a year ago, I wrote a post about the 5 types of architecture diagrams which described many of the diagrams we use today. It walks you through how and why you should create diagrams like the flow, service, persona, infrastructure, and developer diagrams.

They loosely adapt to the c4 model for diagramming software architecture. There are nuanced differences and both help drive important information about your app in different ways.

The other day, I was prepping for a tabletop exercise for an application getting ready to go live and I was reading through my list of architecture diagrams. But something was missing.

I needed a diagram that shows critical paths through the system so I could prepare a realistic disaster scenario. Something that generalized the architecture, but was also specific enough to give me enough detail to know where the break points are in my application.

None of the diagrams I spoke about in my other article cover that scenario. I needed a new type.

I needed the critical path diagram.

Overview

The critical path diagram is meant to be a map of your entire ecosystem. It traces the data flow of the major business processes from system to system. All jumps, fan outs, webhooks, etc are documented so you can easily identify points of failure.

Critical path diagram example

With this diagram, you can follow the data through the entire system. It traces how the data is transferred internally in your application and it follows all the jumps between systems. If a primary business process results in 3 or 4 applications being updated, this is the perfect diagram to illustrate it.

Audience

This type of diagram has a little bit of something for everyone. It has detail from the top to the bottom, making it invaluable for people from support, your product team, and developers.

Considerations

You don’t need to put all the detail for every API in the critical path diagram. You should generalize and group similar endpoints together. If you have a set of endpoints that all technically follow the same flow (for example, API Gateway to Lambda to DynamoDB to DynamoDB streams), you can include that pattern one time.

Data Flows

When talking about data flows, I mean the path through your system a business process follows. If we take an example from Gopher Holes Unlimited, we can see what happens when a new gopher is added to the system.

Data flow for adding a new gopher

Components

• Initiator - Where the business process or data flow begins. Represented in the diagram as a star
• Application - A distinct stand-alone application that plays a part in the ecosystem
  • Known Apps - An application that you own or know how it is structured internally. Represented in the diagram as a outlined white box
  • 3rd Party Apps - Applications you do not own nor know how they work. Represented in the diagram as a black box
• Data Flow - A series of connected lines that show the progression of data through your system. Represented by dashed lines for async calls and solid lines for synchronous calls. When showing multiple data flows, it is best to organize by color.
• Infrastructure - For known apps, this shows generalized details about how the application is built and what services manipulate the data as it flows through the system. Represented by images of the services involved.
• UI Interaction - Actions like filling out forms or performing searches that usually start a data flow. Represented by a rectangle with a label

In our example above, the initiator of the data flow begins on the Add New Gopher UI interaction. For this business process the interaction is a wizard in the UI that walks a user through adding all the necessary data elements for a gopher. When we trace the arrows, we start at the star.

The flow uses the search mechanism to look for existing gophers. That search endpoint uses AppSync to find gophers from DynamoDB, a helper Lambda function, and by calling an API in the National Rodent Registry.

Once data is submitted, it goes through the primary data ingest flow, which goes API Gateway to DynamoDB to DynamoDB streams to Step Functions (that pattern is described in this post).

Once completed, an SNS topic publishes a message which is picked up by Zapier to pass the data along to the 3rd party apps Varmint Hunters Collective and Small Animal Preservation Society. It also publishes to the National Rodent Registry, which takes in data via an ALB on top of an auto-scaling EC2 fleet.

Once the data reaches the integrators via SNS, our data flow is done. By tracing the arrows, we see that four systems are updated when a new gopher is added. Sounds like an important data flow!

This business process is a perfect example of why the critical path diagram is important. It makes sure you can see the most important data flows. Or the most fragile. Or the busiest. Building a critical path diagram will show you each service data passes through, making it easier to isolate problem areas before they become an issue.

Make it Interactive

Putting all of your primary data flows on the same diagram will make it appear dense and complicated. This can make it hard to follow and appear overly complex. It might turn people away from attempting to figure out what is going on.

On the flip side it also helps to show complex, high traffic, or big blast radius areas of your app. Showing that data density is important, but not always.

That said, making your critical path diagram interactive is key to making appear simpler and easier to follow.

I draw all of my diagrams in a free application called diagrams.net (formerly draw.io). When building critical path diagrams, I put each data flow in its own layer. I then add buttons in the key that toggle the visibility of the layer, making it easy to show/hide entire flows.

Critical path diagram key

These buttons live in the key so they are consolidated in a single place. Consumers of the diagram can click a button to hide all the data flow lines or click it again to bring it back. Diagrams.net offers a complete step-by-step tutorial on how to create layers and make buttons that show and hide them.

To see the interactive version of the Gopher Holes Unlimited critical path diagram, click here.

Use Cases

There are several use cases for the critical path diagram.

• System chart - Lists out all applications involved in your ecosystem and how they are coupled
• Disaster Planning - Identifies potential bottlenecks and areas with a high blast radius if a disaster were to occur
• Architecture Diagram Lite - Shows the types of architectures at play. Gopher Holes Unlimited is a serverless application, the National Rodent Registry is a containerized auto-scaling ec2 app, etc…

Each one of these use cases is vital to building a production readiness plan. With the critical path diagram, all the pieces are put in front of you and presented in a way that both generalize and detail how data gets from point A to point B.

You can’t complete a puzzle without all the pieces.

Comparing this to the C4 model, this type of architecture diagram contains elements from the first three levels (Context, Containers, and Components). This provides an interesting, cross-cutting mix of detail at a glance. But the critical path diagram should be supplemented with other types of diagrams. It doesn’t stand by itself to draw the full picture.

You need that last level of detail. You need the nuance of more detailed diagrams to show dependencies or specifics about how things are connected. An infrastructure diagram provides drill-in detail if you need it when you’re walking through disaster scenarios. In the C4 model, this is level 4 (Code).

Final Thoughts

The critical path diagram is a great tool to put in your back pocket. It is an “aggregate” diagram, meaning it combines important pieces from several other types of diagrams into one.

It is used to get a big picture of your entire ecosystem. By providing enough detail to spot throttling and pain points, but abstracting detail out far enough to keep you out of the weeds, it is great for sharing with everyone around the organization. A critical path diagram can be invaluable for developers, support, tech support, and your SRE team.

This diagram does not replace others in your toolbox, but it should be used as an enhancement and a starting point when building system diagrams.

If you’re a solutions architect, a significant part of your job is building a shared understanding with the stakeholders of your application. Building a critical path diagram or really any type of diagram will greatly increase your chances of building that understanding.

Try it out, let me know what you think, and share what you build!

Happy coding!