A technical architecture diagram provides a bird’s eye view of the infrastructure of your organisation. The diagram illustrates how components in a system interact with one another in the large scale of things.

There are various kinds of architecture diagrams serving different purposes. Usually, a digital solution architect will draft out high-level architecture diagrams to facilitate technology solution design. There are two main benefits of an architecture diagram:

1. They help with understanding — provides an overview of the available systems and interaction, which facilitates impact assessment from changes easily.
2. They improve communication and collaboration — aligns implementation plan across projects and stakeholders to reduce gaps in communication. A useful architecture diagram should address each of the stakeholder’s needs to a certain extent.

In this article, I’ll be covering five architecture diagrams which have served me well in designing and implementing digital solutions. They are:

• Application Architecture Diagram
• Integration Architecture Diagram
• Deployment Architecture Diagram
• DevOps Architecture Diagram
• Data Architecture Diagram

A quick note: Best practices usually vary across organisations. I’ll be sharing what has worked for me in the implementation of cloud infrastructure solutions — from an AWS cloud perspective.

Just like software codes, the usefulness of a well-drawn architecture is often overlooked until the systems become large and complex. A useful architecture diagram has a combination of these three components:

1. Standardised process flow of information, e.g. top-down reading — this indicates how the components interact with each other.
2. Provides sufficient information in components with logical groupings — this indicates where constraints lie, e.g. network boundaries.
3. Includes annotations with more information — steps with slightly more details to facilitate the implementation of solutions, e.g. process description.

I’ll try to provide some context and examples of how each diagram is used to help with the design and implementation of a solution.

FYI: The sample diagrams shown below are created using a free tool: https://draw.io/.

#1: Application Architecture Diagram

An application architecture diagram comprises of a high-level overview of the components and fundamental interactions within the system, e.g. microservices, databases, etc.

The application architecture diagram primarily addresses the “What” in relation to the system.

A common usage of this diagram is to facilitate planning and solutions implementation in the form of assessing the impact of upgrading, replacing or merging existing applications. With new applications continually being released into the market and promising increased efficiency and reduced cost (especially in the containerisation space), it’s vital to have an overview of the applications within your system.

For instance, your applications may reside in multiple container clusters, i.e. bare-metal Kubernetes, AWS ECS, etc. due to various reasons; and you are tasked to consolidate and merge the applications to use a single container-management platform, e.g. bare-metal Kubernetes to optimise cost and streamline operations in a multi-cloud environment. As a start, some of these questions may pop up in your mind:

• What type of applications is in each cluster?
• What are the applications’ dependencies and interactions?
• What’s the intended outcome and desired state of the architecture?

The following example diagram below illustrates the as-is state of the application architecture. The components within the “Logic Layer” of the diagram addresses the first two points.

With the questions addressed, assuming the plan is to merge the AWS ECS cluster applications into the Kubernetes cluster, there are a couple of action items that require the inputs from various stakeholders based on the diagram.

For example, you may reach out to the project manager to check on the types of partner integrations, e.g. internal/external, DevOps to check on keys and config management, and the system engineers to check on the way the clusters are organised, etc. to assist with the impact analysis.

After obtaining the relevant information from the respective stakeholders, you’ll then be able to establish the desired/to-be state of the architecture and implementation plan factoring in the important considerations.

Useful components in this diagram:

• Grouped components into layers and bounded contexts — each boundary likely suggests a different stakeholder group, e.g. data engineers for the data layer, core platform team for common/shared services, etc. which provides an idea who to involve in the planning/discussions.
• Annotations with additional information — provide further details about how each cluster is managed and organised, e.g. based on the nature of applications and security concerns, etc. may be included to facilitate discussions.
• Application details and context — state name and types of applications to provide an idea on how applications are organised

You can download a sample of the above diagram here.

#2: Integration Architecture Diagram

An integration architecture diagram is vastly similar to the application architecture diagram, except with the additional emphasis on the integration protocols between the components, e.g. Batch, Events, REST/SOAP/XML, etc.

The integration architecture diagram addresses the “How” with regards to the interconnectedness of components within the system.

A common use of this diagram is to facilitate the integration of external systems by partners or other internal systems. With businesses establishing new partnerships via ecosystems these days to create mutual value these days, you may often have to work with partners to integrate systems together, e.g. e-commerce, payments, hotel bookings, flights, etc.

For instance, there is a partner that has a travel application that wishes to list your product catalogue on their app to increase the choices for their consumers. You are tasked to work with the partner solution architect to facilitate the integration of systems to expose your services to them. The partner prefers to consume services via REST APIs.

Some of these questions may come to your mind:

• How are my services currently organised and exposed internally/externally?
• How does the partner want to integrate with my system, e.g. internal networks, protocols, etc.?
• How do I secure, track and manage the integration of my exposed services?

The following integration diagram below illustrates (at a high level) the existing communication protocols between the components. You’ll also see how some of the services are being exposed to third-party developers via the External API Gateway at the logic layer.

From the diagram above, you’ll realise that the system was designed to be API-driven, which makes it easy for integration. Almost all the services are exposed via web services, including the data storage components.

The next step is to check with the partner on the list of services that they require, mode of integration, e.g. internal or external, and cross-reference the requirements with the services exposed via the API catalogue. There are also follow-up action items, i.e. working with the system engineers to decide on the security and monitoring of exposed services.

Sometimes, there may be requirement gaps such as partner wants to integrate externally, but your services are only exposed internally, or certain data attributes are missing. In such cases, efforts would have to be factored in to cater to the requirements. The integration diagram has to highlight details, i.e. internal services/APIs, link to API catalogue, etc. to identify such gaps quickly.

Useful components in this diagram:

• Grouped components into layers and bounded contexts — an indication of internal/external API gateways and services
• Annotations with additional information — reference links to API catalogues where detailed service data attributes can be obtained to assess gaps
• Application details and context — services are named appropriately to allow quick assessment of requirements v.s. actual

You can download a sample of the above diagram here.

#3: Deployment Architecture Diagram

A deployment architecture diagram consists of network boundaries and infrastructure hardware/software components. The size and quantity of the components are also sometimes specified in order to facilitate planning.

The deployment architecture mainly addresses the “Where” and “How many” with regards to the components in the system.

A common use of this diagram is to facilitate the upgrading of applications and services to handle the additional load or the optimisation of resources. Over time, as more users from various parts of the world start using your applications and services, your existing resources may not be able to handle the increased scale and load.

For instance, your API gateway is currently deployed in a single large EC2 instance (t2.xlarge) and has been facing intermittent service disruptions due to performance lately. You are tasked to convert the API gateway to a cluster setup (with new machines) in multiple availability zones (AZ) to improve the availability of the gateway. Some of the questions that may come into your mind are:

• How many AZ?
• Where to deploy the instance?
• How large would the new instance be?

The deployment architecture below illustrates the current setup of the network and components. There are two AZs for the current application with the API gateway instance in ap-southeast-1.

Based on the diagram above, you’ll be able to obtain information on the existing sizing of the API Gateway instance, e.g. (t2.xlarge), to serve as a benchmark for the new instance sizing. There is also a corresponding database instance tagged to the API Gateway instance in the same availability zone.

The diagram could also prompt further discussions on the location of the new instance, i.e. private subnet-2b or 2c, etc. or whether there could be further plans to consolidate a central API gateway for all the services on the AWS Core Platform to centralise API management.

The next step would be to estimate the impact based on the various implementation plans, i.e. centralised API management or decentralised, etc. and propose to management and respective stakeholders for evaluation.

There are often various approaches to resolving such performance issues. If you’re in a large organisation, it’s important to align the approaches via a central architecture committee for proper architecture governance.

Useful components in this diagram:

• Network boundaries — showcases the isolation of components and potential connectivity implications.
• Instance sizing — indicates the sizing of the machines to facilitate optimisation and benchmarking of resources with respect to performance requirements.
• Show parts of external integration — showcase the system’s extension (if any) to other systems and networks to indicate a larger picture and facilitate streamlining of resources, i.e. common/shared services, etc. and collaboration opportunities.

You can download a sample of the above diagram here.

#4: DevOps Architecture Diagram

A DevOps architecture diagram often comprises of system components, processes, and environments. The diagram resembles a process flow diagram illustrating the operations to ship a codebase/app to production.

The DevOps architecture mainly addresses the “How” and “What” in relation to the optimisation of processes and deployment flows.

A common use of this diagram is to facilitate the improvement of processes with regards to app deployments. The constant changes to systems architecture and improvements to deployment tools/methods, e.g. Containers, Serverless, etc. prompts a need to adapt existing DevOps architecture and processes to keep up with the times.

For instance, applications management, e.g. configs, etc. for your team are currently non-standardised across platforms, and you are tasked to explore the implementation of a new tool (Habitat) to effectively manage the applications. Some of the questions that might come to your mind are:

• What’s the current process flow?
• How are configurations currently managed across applications?
• What are the types of applications to be deployed?

The DevOps architecture below illustrates the process flow to deploy applications into a Kubernetes cluster across the environments. There could be multiple variants of the diagram for different application types.

Based on the diagram above, you’ll be able to obtain information on the various stages of the DevOps flow to identify processes that can be enhanced by the new tool, e.g. config management, or integration points to incorporate the new tool(s).

DevOps diagrams of various application types could prompt further discussions to explore a potentially new set of processes and tools to cater to the team’s needs.

The next step would be to involve the various stakeholders to discuss process and tools improvements as well as the potential impact on existing operations with the implementation of Habitat, e.g. new plugins required, etc.

For large organisations, the processes are much more complex with security concerns across the environments which restricts the deployment of resources heavily. There are also many legacy applications which follow old methods of deployment. It’s advisable to document the processes for the different application variations and look at them as a whole in order to improve efficiency.

Useful components in this diagram:

• Showcase processes across environments — DevOps usually span across environments, and it’s often useful to show the applications promotion processes.
• Annotations with additional information — further details for the respective stages and processes can be included to facilitate discussions and planning.
• Decision gateways and user processes — DevOps don’t only include system components and involves a large part of the human element to build a good DevOps culture; the human processes component cannot be ignored.

You can download a sample of the above diagram here. Also, here’s a list of 31 reference architectures for DevOps.

#5: Data Architecture Diagram

A data architecture diagram contains components within a system that define how data is collected, processed, stored, and used. The diagram also illustrates the flow of data across system components within the IT infrastructure.

The data architecture diagram addresses the “How” and “Where” in relation to the processing, flow and usage of data.

One of the use cases of this diagram is to facilitate the upgrading of resources to optimise data collection and storage costs. With the increasing amount of data captured today and the cost of data storage getting cheaper, there are bound to be constant adjustments to the data architecture for organisations.

For instance, logs data captured from the API gateway is currently stored in a MySQL database and visualised on a web dashboard. As data builds up over time in the database, queries became slower and more costly. You are tasked to resolve the performance issue and set the foundation for future machine learning and analytics capabilities on the data sets from other applications. Some of the questions might come into your mind:

• How is data being processed currently?
• Where is the data being stored and used?
• How much data are we talking about?

The data architecture below illustrates the flow of data from the source to storage and visualisation. In some cases, it may be useful to include new components in the diagram to show the changes to facilitate discussions.

The diagram above addresses the questions with regards to the processing, storage and rate of data increment — which would be sufficient to kickstart discussions on exploring potential alternatives to support new querying systems and business use cases.

The next steps could be to involve stakeholders to discuss implementation details, e.g. data retention periods, performance requirements, business objectives and insights, data structures and models, cost estimations, etc.

In large organisations, there would likely be a central data management team in charge of consolidating and managing the master data components and processes. It’s advisable to set a common standard to be applied (as much as possible) across the applications within the organisation through the use of such diagrams.

Useful components in this diagram:

• Display as-is and to-be components — provides an overview of the changes at a quick glance to assess the impact and focus discussion points.
• Indication of data increment rate — gives stakeholders a sense of the scale of data for estimation and solution design purposes.
• Logical grouping of components — illustrates the objectives of the components at the various stages, e.g. processing, visualising, etc. to facilitate ease of readability.

You can download a sample of the reference diagram here.

Takeaways

1. Application architecture diagram provides a high-level overview of components to facilitate planning in the form of impact assessments based on the upgrading, replacing, and merging of applications.
2. Integration architecture diagram focuses on the integration protocols between the application components to facilitate the integration of internal/external partner systems.
3. Deployment architecture diagram highlights the network boundaries and sizing of infrastructure components to facilitate planning and upgrading of applications and services for optimisation purposes.
4. DevOps architecture diagram illustrates the flow of processes involving systems and humans across deployment environments to facilitate process improvements and automation.
5. Data architecture diagram showcases the flow of data across system components within an IT infrastructure and indicates how data is collected, processed, stored, and used to facilitate data systems optimisation.

These diagrams are often used together in digital solutions design as they complement each other to provide stakeholders with a picture of the system.

However, bear in mind that the map is not the territory. It’s almost impossible to document every part of the system given the number of moving parts and changes. I’ve faced many instances where changes and components were not captured in the diagrams due to various reasons. Be prepared to deal with such scenarios.

Also, there are many variations of architecture diagrams (based on Google images) catered for different purposes — there’s no fixed way of drawing architecture diagrams. What I’ve provided here are sample guidelines and principles to assist with a better understanding of the systems to work out a potential solution.

At the end of the day, these diagrams are tools to facilitate communication and understanding, and it’s essential to tailor the diagrams to suit your team’s needs and style.

Article originally published on medium.