You must either design solutions or review proposed solutions if you are reading this note. Whatever position you occupy in your organization (solution architect, enterprise architect, etc.), your primary work deliverable and/or artefact must be a diagram that this title captured your attention!
I want to underline that the purpose of architecture from Kent Beck language in Extreme Programming Book, before I continue.
To give everyone a coherent story within which to work, a story that can easily be shared by business and technical folks.
These days, receiving tens of comments and questions on a single architecture diagram is routine, ranging from scope to components to missing functionality. But how can you, as a solution designer, reduce the volume of concerns, comments, and questions? What information should a diagram provide about a system architecture in order for your stakeholders to grasp it and make a decision or take action toward implementing the recommended solution? How about the completeness of the scope? How detailed should the elements be depicted?
What you'll see here is based on a real-world application (as one of many kind) diagram I had to evaluate, and it will help put things into perspective for you:
I realized the solution architect was hinting at a n-tiered design, integration with external systems, and database access to a third-party application at first glance. The architect also proposed using the single sign-on (SSO) that the enterprise she is working for preferred. However, this was insufficient to decide or sanction the start of a project.
The following are some of the primary questions that came to mind when I saw the above application architecture diagram at first:
- What did the architect want to say by mentioning development stack in an application diagram? In other words, what is the point of disclosing those details in such a diagram?
- What does "Presentation Layer" and "Business Logic" mean when the diagram shows the same stack, and the API Manager Layer is somehow underneath the business logic?
- How can displaying a DB icon in the Integration component from the API Manager layer help?
- What are the specifications of the integrations with other platforms and services? (For instance, who is the producer and who is the consumer? Is it async or sync integration? How often will this integration be executed? and …)
- What problem precisely is this piece of technology trying to solve? Why are there no details and clarity about the application's major components?
- Is it necessary for an architectural decision maker to understand the operating specifics (such as pipelines, IDEs, and so on)?
- What is the rational and message that Infrastructure Layer wants to convey here in an application context?
... so many additional questions that caused me to radically reconsider the authenticity of this diagram. As such, the problems with the many architecture diagrams like the above instance in summary is:
- Not enough Clarity: The diagram is clunky and contains confusing notation which making it difficult to understand the system's structure.
- Exaggerated Representation: The diagram does not fully depict the actual structure of the system, which might lead to misconceptions and false assumptions about the system's architecture.
- Components Lacking: If critical system components are left out of the diagram, it might lead to an incomplete or inaccurate picture of the system's design.
- Inadequate Layout: It can be hard to decipher the links between the components if the diagram is inadequately drawn up, with components clashing or situated in a confusing manner. (Do not underestimate the role of “Arrows” in an architecture diagram in general which I expand this later)
- Over Complicated: It might be intimidating and difficult to grasp if the diagram is extremely complicated, with several components and relationships. It is critical to achieve a blend between thoroughness and simplicity.
Of course, someone who has worked in the same organization for a long enough period may have answers to some or all the problems I stated, yet that's not the point at all!
The architecture artefacts are not only intended for internal usage (by internal I mean within a pod, team, or small community within a technical or operational function). Architecture artefacts are useful documents for onboarding and giving top management a foundation for important choices. The size and complexity of the organization you have thus far served have most certainly stymied your ability to answer such queries. As a result, this may be the time to assess the quality of the diagrams and establish some parameters for architecture diagrams.
OK, now let's get down to brass tacks and define some terms.
What is an Architecture Diagram?
Some say an architecture diagram is a visual representation of every component that makes up a system, in whole or in part. Above all, it aids in the understanding of a system (IT systems in this context) by engineers, other architects, stakeholders, and anyone else involved in the project.
Architecture diagrams are used in another narration to represent the high-level structure of an IT system, demonstrating how the various components fit together and interact. An architecture diagram is meant to give a quick and clear overview of the system so that stakeholders can understand its structure and design and make smart decisions about its development and maintenance.
As was already said, architecture diagrams are often used to explain to different stakeholders the structure and design of a system. As a result, they are one of the most important architectural materials. Hang on! different Stakeholders?! Yes, let us take a quick look at some of the stakeholders.
Developers and/or Engineers
Usually, architecture diagrams will be used for onboarding and for development/engineering teams working on different parts of the system to have a bigger picture of how their deliverables will contribute to a digital product or technology. Furthermore, it must provide enough information for developers/engineers to implement systems based on the objectives established during the solution design process.
Project Managers
PMs can utilize architecture diagrams to plan and manage system development and maintenance, as well as to comprehend external system dependencies and the potential implications they will have in terms of resources and budgeting.
Business Analysts
BAs can use architecture diagrams to determine what the system can and cannot do, as well as ways to improve or grow it in the next iteration based on business requirements and priorities. Furthermore, architecture diagrams will serve as a high-level checkpoint for business requirement validation if they are clear and simple enough for business analysts to understand.
Executives (and/or higher management)
Architecture diagrams can assist executives and other high-level stakeholders in understanding the system's overall design and structure, allowing them to make strategic decisions about systems’ potential and probable future investment, etc. (It would be naive to imagine that one executive will decide only based on a single architecture diagram, but that would be one of the data points that may serve them well in the decision-making process.)
Enterprise Architects
I previously took some notes on enterprise architecture, which you can find by beginning to read at http://blogs.malekmakan.com/post/rethink-enterprise-architecture to get the idea I am bringing up in this note.
There, the goal of enterprise architecture is defined as
Increasing project success rates by providing adequate planning materials, decreasing response time to business changes by implementing new business capabilities, and finally eliminating redundant activities by providing or becoming a one-stop shop for enterprise constraints and being connected to actual work on the ground.
According to the given definition for an enterprise architect, tracking the IT landscape size, application and technology inventory, and business capability mapping, information architecture included pre-requisites such as data and technologies used, as well as integration specifications that were considered on a daily basis.
As a result, architecture diagrams are critical enterprise artefacts for first aiding in the maintenance of the enterprise IT landscape and second assessing the proposed solution against enterprise level standards and compliance.
Overall, those controls and gatekeeping will lead to more efficient rationalization practices and strategic enterprise decision making that directly serves the business's interests.
Numerous different stakeholders may use an architect's deliverables depending on the design environment. It may differ depending on the View and Context of the problem that one architect is attempting to solve, for instance, Data Management teams are more interested in Data Flow and Data Sources for lineage inventory, whereas Cloud Engineers are more interested in Infrastructure and Cloud design diagrams. Overall, all those domains are of great relevance to enterprise architects (Business, Data, Application and Technology)
What Are the Most Notable Aspects of an Architecture Diagram?
It is time to get to some recommendations which makes architecture diagrams more matured and effective:
A representation of a system from the perspective of a related set of concerns.
Before drawing a line on paper, consider what type of diagram in the IT area you want to create. For example, if you are designing an application, you cannot have a combined view of Infrastructure, Network, and Application in a single diagram. Because this point of view will not communicate any of those ideas successfully or fully.
- Consistency: As mentioned, diagrams shall have a consistent visual lexicon or language. The solution architect must set the contract (or better, follow one of the well-known standards like UML, Archimate, or such) and be consistent across the diagramming activity. The standards might be enforced by respective organizations and one solution architecture shall follow.
- Abstraction: Diagrams should abstract the system's low-level details to focus on the high-level components and their relationships. The designer's ability to think abstractly will often result in a good design. It is critical to emphasize that the level of abstraction must remain consistent to avoid further mix-ups and confusion for audience. The act of creating a diagram compels the audience to think at a single level of abstraction at once. Hence, the level of abstraction shall be consistent!
- Clarity: Diagrams should be easy to decipher. Arrows that are clearly labelled and correctly employed, and use of relevant icons can be game changer. I’d like to add here that a clear diagram shall expose Containment & Proximity to its audience. The terms Proximity and Containment are referring to the real-world semantics. That is to say, the diagram shall reflect the hierarchy and vicinity of the components as they exist in the real world.
- Accuracy: Diagrams must accurately portray the true structure of the system which is subject of design. In addition to high level structure, a well-tuned diagram will exhibit coupling, cohesiveness, logical partitioning/grouping and relationships.
- Completeness: Within the scope of the work, diagrams must incorporate all necessary components and their relationships. The system's key components must all be represented in the diagram, along with their interrelationships. Examples of such components include user interfaces, database systems, computing, business, and external systems, or solutions. The interaction of these parts, including the flow of data and control, must also be easily understood.
- Scalability (Maintainability): Ultimately architectural diagrams must be continuously updated or extended to reflect modifications or improvements to the system it depicts without requiring the full diagram to be redrawn. In other words, scalable architectural diagrams are intended to retain their viewpoint, consistency, abstraction level, clarity, accuracy, and completeness as the system they portrayed expands or varies with time.
More about Arrows!
Without arrows, Architecture Diagrams are unlikely to be useful and comprehensible unless you are designing a reference model or architecture from a 30,000-foot perspective (which is out of the scope of this note, but I promise to share my notes on RA soon).
The lines are more interesting than the boxes
Arrows in architecture diagrams should demonstrate how data or control moves from one component to the other. For example, an arrow between components can indicate that the first component is controlling the second component or transferring data to the second component.
If we consider 3 major aims in architecture diagrams that one solution architect draw is to define system Components and the Relationship between them to explain system Behavior in a given context. So, removing Relationship (which is frequently represented by lines in general and arrows in particular) leaves us with a slew of wooden components, screws, nails, and unknown pieces with no instructions on how and in what sequence to assemble our IKEA furniture, if I may use that analogy:
When utilizing arrows in architectural diagrams, there are a few important things to bear in mind:
- Label the Arrows Succinctly and Clearly: The arrow labels should clearly and succinctly identify the type of data or control being delivered. In other words, what kind of relationships two components have which may impact the behavior of the system.
- Style Arrows Accordingly: Different arrow forms can send various messages. A solid arrow, for instance, can represent a strong or direct association, whereas a dotted arrow may represent a weaker or indirect one. This type of arrows and their shape and pattern are depending on the framework or design language you consistently employed for the piece of design you are drawing.
- Don't Overdo It: Though arrows can be helpful for illustrating relationships between components, they should not be used excessively. Having arrows with varied forms, colors, patterns, and so on creates extra noise and is inconvenient.
Details in Architectural Diagrams, at What Level?
The audience and the diagram's intended use should determine the level of detail in an architecture diagram. In general, it's crucial to find a balance between giving the audience just enough information to understand the system's structure and design while avoiding giving them too much information.
For High-Level Designs, it may be sufficient to contain merely the primary components and their relationships, without delving into too much detail about each component's internal dynamics. This can be useful for stakeholders who are primarily interested in understanding the system's overall structure and design.
If, on the other hand, the diagram's objective is to illustrate the system's Low-Level Design, more extensive information about the components and their relationships may be required. This could include details about the functions, data structures within each component, modules and their specifications as well as the interconnections between them.
In general, it is important to consider the needs and goals of the audience when determining the level of detail to include in the diagram. The diagram should provide enough information to effectively communicate the structure and design of the system, without being unnecessarily complex or overwhelming.
Closing and Next Step
I attempted to explain and describe some generic material that a solution architect may use to create better architectural diagrams. There are many more factors that may or may not be stated in this remark, but those specified in the scope are the most common in my view.
From here, I feel I would provide more extensive comments on the many sorts of architecture diagrams and their differences. This will be an effort to address certain questions such as:
- Can you please outline the requirements for an Application Architecture Diagram?
- What elements should be represented in an Integration Architecture Diagram?
- How in-depth should an architect look into Data Architecture Diagrams?
- How do diagrams of application architecture and cloud/infrastructure/technology architecture intersect, if at all?
- Where should we put Security considerations in the various architecture diagrams?
- And a great deal of similar inquiries...
Cheers,
Mohammad Malekmakan
Disclaimer:
All opinions and content published in my blog and my social networks are solely my own, not those of my employer(s) and the communities I am contributing in.