Using Architecture Diagrams for better cloud development

Working on cloud software team projects can be very productive and a lot of fun but you probably know a common scene: It’s Monday morning and you’re working on a product catalogue service and what used to work on Friday suddenly brings up an error. You bring up the issue at the daily team meeting and one of the other developers pipes up with “Oh yeah. I made a change to the shopping cart API, so it works better now. It shouldn't affect your service.” Ok, so what went wrong? You’re both using RESTful APIs, so it should just work — right?

Obviously in reality it's not that simple. In order for a team to work efficiently on separate parts of a system, they need to have a clear understanding of how the services interact with each other. This is where an Architecture Diagram (AD) comes in.

What is an Architecture Diagram?

In short, an architecture diagram is a visual representation of the components, relationships, and overall structure of a software system, helping to guide its design, development, and maintenance. It is composed of various elements such as modules, interfaces, and connections, which together illustrate the system's organization and interactions.

A short history of Architecture Diagrams

Life before Architecture Diagrams?

In the world of software development, architecture diagrams serve as a visual blueprint for a software system's design and structure, much like an architect's blueprints do for a building. These diagrams have been a staple of software development for many years, providing a visual representation of a software system's components and how they interact. However, with the emergence of agile software development methodologies in the early 2000s, the use of architecture diagrams has evolved and become more important than ever.

Architecture Diagrams, Agile and DevOps

Agile and DevOps are two methodologies that share a common goal of delivering software quickly and efficiently. Agile focuses on iterative development and collaboration between team members, while DevOps emphasizes automation and continuous delivery.

Architecture diagrams are a useful tool in both Agile and DevOps because they provide a clear and shared understanding of the software system's design and structure. This understanding helps to ensure that all team members are aligned and working towards the same goal. Additionally, architecture diagrams can help with the automation and continuous delivery process by making it easier to identify and address potential issues before they become major problems.

The benefits of Architecture Diagrams

The process of working on architecture diagrams has a number of positive influences on software projects, beyond the simple benefits of being more organised:

• Clarity: Ensures everyone understands the software system's design and structure.
• Collaboration: Provides a shared reference point, making it easier for team members to work together.
• Flexibility: Easily modified to accommodate changes in requirements and design decisions.
• Risk Mitigation: Identifies potential design issues early, reducing the risk of major problems down the line.
• Efficiency: Allows development teams to work more efficiently and with greater confidence.

The AWS Well-Architected Framework

A well-architected system is designed to support the organization's business needs while optimizing for efficiency, security, reliability, and cost. One of the key components of a well-architected system is a well-designed architecture diagram.

Source: AWS Well-Architected Framework

As you may be aware, the AWS Well-Architected Framework (WAF) is a set of best practices for designing and operating cloud systems that are reliable, efficient, secure, and cost-effective. The framework provides guidance on how to design, deploy, and operate cloud architectures that meet the highest standards.

Architecture diagrams naturally play a central role in the AWS WAF, as they allow teams to document and visualize their cloud systems' design and operation. They also help ensure that systems align with best practices and that potential issues are identified and addressed early.

Beyond that, ADs are also useful for evaluating trade-offs between different design decisions and promoting collaboration among team members — helping them to satisfy the key objectives of the WAF in building Well-Architected systems.

Use Cases of Architecture Diagrams

Communicating, collaborating and sharing

A quick straw poll of the development staff at PCG revealed that the most popular use for Architecture Diagrams was in communicate the design of a system to others. As such, they can be very useful in situations such as the following:

1. Communicating the system's design and operation to stakeholders such as developers, architects, project managers, and business stakeholders.
2. Collaborating with other teams to ensure that their services integrate with the overall system, and that any dependencies or potential issues are identified and addressed.
3. Sharing architecture diagrams during code reviews to ensure that the code aligns with the overall architecture and design principles.

Architecture diagrams are a valuable resource for documenting a system's architecture, including data flows, components, and their interactions. They enable teams to create a living document that can be updated as the system evolves, ensuring that everyone has access to the latest information.

Evaluation & Optimization

Whilst it’s a less common use case, the WAF also recommends that architecture diagrams can be used to help optimize a well-architected system in a more proactive way than simply documenting:

1. Evaluation of the system's performance and identifying areas for optimization, such as optimizing the use of AWS resources, improving response times, and reducing latency.
2. Assessment of the system's security posture, including identifying potential vulnerabilities and recommending mitigations.
3. Analysis of the system's cost and identifying opportunities to optimize spending, such as identifying underutilized resources or optimizing usage of reserved instances.

Practical Tools and Resources

1. Drawio (previously diagrams.net)
   A free, open-source online tool for creating a wide variety of diagrams, including architecture diagrams. It offers a user-friendly interface, a wide range of pre-built templates and shapes, including all the standard AWS and Azure services.
2. AWS Architecture Center
   A free online resource provided by Amazon Web Services (AWS) that offers a wealth of information on AWS architecture best practices, reference architectures, and example diagrams.
3. AWS Reference Architecture Diagrams
   A collection of pre-built architecture diagrams for common use cases on the Amazon Web Services (AWS) platform, plus a collection of downloadable AWS Architecture Icons to communicate your design, deployment, and topology.

Are they the best thing ever?

When there’s a lot of talk about how useful a tool or technique is, it’s difficult not to think that there must be some exceptions to the rule. What about small or simple projects with few dependencies or data flows? Can fancy diagrams still help? In these cases, sure, it might add unnecessary complexity (and be a bit of a drag) to have to keep drawing things out.

However, while architecture diagrams may not always be strictly essential for small projects, they can still be useful for clear communication and understanding among stakeholders. Plus, having a diagram can help with future maintenance and scalability of the system, so it's worth considering creating a simplified diagram that captures the essential components and their interactions, even if it's not too elaborate.

Architecture Diagrams: the blueprints of success

As we’ve seen above, architecture diagrams are super important in agile software development, especially for cloud applications. They help teams plan, design, and run their systems in a reliable, efficient, secure, and budget-friendly way. Well-drawn diagrams also make it easier for everyone to understand what's going on, speed up the development process, and keep making things better as they go along. Using architecture diagrams, teams have a tool that can help them build and maintain awesome cloud applications in today's competitive world.