Documenting Solution Architecture: Introduction

‌                                            

One of the responsiblities of a Solution Architect(as I mentioned in one of the talks) is to document the Architecture in order to communicate it to all the project stakeholders: Project Manager, CTO, Project Sponsor, Development and QA teams and others. The needs for such communication are the following:

• Understand what components the system consists of
• How those components communicate with each other
• How and where different parts are deployed to
• How the system in general fulfill the requirements

Missing any of that information can easily lead to the project being late, overtime or cancelled.

Let's start with an example

Each software system is rather complex. The first attempt to document it is to try to draw some kind of a diagram to include everything, which fails very quickly. Imagine we want to document some relatively simple one, say, this particular blog you're reading the article on. It is powered by the Ghost CMS storing the data in MySQL database; Apache is used for the web server. The requests are handled by the webserver, redirecting all requests from http to https and addressing the requests to the CMS. CMS validates the tokens and asks the database for the content including pages, blog posts and plugins. All three components run in a VM in GCP in the default network in a separate organization. The system is accessed by the readers and content managers, the latter can add new content and edit the current one. The system also can be altered by system admins through the cloud console. I will try to include all this information on a single diagram:

‌

You can say this is a decent diagram however it has the following problems:

• Overloaded. To answer any particular question you have to search for details.
• Insufficient. Say, how many regions the system is deployed to? Is the database or VM backed up? Where are images stored?  How the users are authenticated? You can't answer these questions from the diagram.
• Misleading. Why there are green, blue and yellow rectangles? What does it mean?

I wanted to talk to you about Views and View Points, how it is described in Documenting Software Architecture by SEI, but I find this approach a bit too academic. Let's keep it simple with the following statements:

1. You can't put all the information on a single image
2. You absolutely don't have to do so
3. Instead you provide a set of pictures so that each of them fits perfectly for a particular stakeholder(a person interested in your project)

There are several approaches to that(Modules-Components&Connectors-Allocations, C4 approach, etc), it doesn't matter what you pick. The main thing is that you want to allow 1 person at a time to get maximum of the information within minimal time period.

Split the concerns

For our system we have the following interested people(stakeholders):

1. Project Sponsor
2. Blog author
3. System Administrator
4. Content Manager
5. Reader

Their corresponding concerns are the following:

We can say that the Project Sponsor is not interested in diagrams at all: he/she require only a dollar value of operation cost. System administrator though wants to see the diagrams answering the following questions:

Whom the system interacts with?

This diagram is called Context Diagram(by C4 notation) which shows exactly that: what are the agents the system speaks to. See, there is a block "Analytics" here. I literally forgot about it while drawing the first one, but looking at a certain level allows to focus on a particular aspects and not miss anything.

How and where the system is deployed?

This diagram shows that the solution is Deployed to Google Cloud Platform, to a single VM on a single network within single region, the access is protected by Cloud IAM. Basically, it answers how much money roughly the solution cost(20-30$ monthly depending on the region and VM size), and that it scales poorly and will require a redesign in case of drastic load increase. Also, there is no DB backup in place, so actions should be considered immediately.

This diagram however does not provide the data about which components are deployed to the VM, but this is the responsibility of another diagram.

See, how we focus on a particular aspects at a time? Do you see how easier to grasp the information now?

What is the functionality of the system?

Here we can clearly see what are the features our CMS is providing so that Content Managers and Blog authors are capable of working on a content: creating posts and pages, uploading images and embedding the 3rd party content. Also, we can see that the CMS itself handles user authentication.

Looks like we addressed the most of the questions just within 3 simple diagrams. Good job!  

Summary

Today we learned how to identify the concerns and provide the corresponding views. However, there is still a lot to cover for a production project which is typically done in a big document which is called "Solution Architecture Document": I will be talking about it in the upcoming posts.