What is a Software Architecture Document and how would you build it?

After working as a senior designer and a software architect in three sub-continents and four countries, I have come across to a phenomenon in Australia! I call it a phenomenon because first of all, terms such as ‘solution architect’, ‘software architect’ and/or ‘enterprise architect’ are used interchangeably, and even sometimes incorrectly. Secondly and surprisingly, the architecture tends to be done by made-up methods and the documentation is either non-existent or is written in a language that is not standard.

This leaves the project owners with a whole bunch of documents which are not understandable to them so that they have to hand them over to a development team without even knowing if the design is what they really wanted.

I believe this happens probably because such a crucial task is given to a senior developer or who has a pure technical mindset, whilst an Architect must be able to look at the problem from various aspects .

Dependency Injection in .NET Core 2 with C#
Dependency Injection in .NET Core 2 with C#, From Beginner To Advanced!

What is Architecture?

Architecture is the fundamental organization of a system embodied in its components, their relationships to each other, and to the environment, and the principles guiding its design and evolution (IEEE 1471).

The definition suggested by IEEE (above) refers to a solution architect and/or software architect. However, as Microsoft suggests there are other kinds of architects such as a Business Strategy Architect.

There are basically six types of Architects:

·        Business Strategy Architect

The purpose of this role is to change business focus and define the enterprise’s to-be status. This role,  is about the long view and about forecasting.

·        Business Architect

The mission of business architects is to improve the functionality of the business. Their job isn’t to architect software but to architect the business itself and the way it is run.

·        Solution Architect

Solution architect is a relatively new term, and it should refer also to an equally new concept. Sometimes, however, it doesn’t; it tends to be used as a synonym for application architect.

·        Software Architect

Software architecture is about architecting software meant to support, automate, or even totally change the business and the business architecture.

·        Infrastructure Architect

The technical infrastructure exists for deployment of the solutions of the solution architect, which means that the solution architect and the technical infrastructure architect should work together to ensure safe and productive deployment and operation of the system

·        Enterprise Architect

Enterprise Architecture is the practice of applying a comprehensive and rigorous method for describing a current and/or future structure and behaviour for an organization’s processes, information systems, personnel and organizational subunits, so that they align with the organization’s core goals and strategic direction. Although often associated strictly with information technology, it relates more broadly to the practice of business optimization in that it addresses business architecture, performance management, and process architecture as well (Wikipedia).

Solution Architect

As we are techies let’s focus on Solution Architect role:

It tends to be used as a synonym for application architect. In an application-centric world, each application is created to solve a specific business problem, or a specific set of business problems. All parts of the application are tightly knit together, each integral part being owned by the application. An application architect designs the structure of the entire application, a job that’s rather technical in nature. Typically, the application architect doesn’t create, or even help create, the application requirements; other people, often called business analysts, less technically and more business-oriented than the typical application architect, do that.

So if you are asked to get on board and architecture a system based on a whole bunch of requirements, you are very likely to be asked to do solution architecture.

How to do that?

A while back a person who does not have a technical background, but he has money so he is the boss, was lecturing that in an ideal world no team member has to talk to other team members. At that time I was thinking that in my ideal world, which is very close to the Agile world, everybody can (or should) speak to everybody else. This points out that how you architecture a system is strongly tight to your methodology and mindset. It does not really make a big difference that which methodology you follow as long as you stick to the correct concepts.

 What the above story points out to me is that solution architecture is the art of mapping the business concerns to technical matters, or in the other words, it’s actually speaking about technical things in a language which is understandable to business people.

A very good way to do this is by putting yourself in the stakeholders’ shoes. There are several types of stakeholders in each project who have their own views and their own concerns. This is the biggest difference between the design and the architecture. A designer thinks very technically while an architect can think broadly and can look at a problem from different angles.

Designers usually make a huge mistake, which happens a lot in Australia: They put everything in one document. Where I am doing a solution architecture job now, I was given a 21-mega-byte MS Word document which included everything, from requirements to detailed class and database design.

Such a document is very unlikely to be understandable by the stakeholders and very hard to use by developers. I believe that this happens because firstly designers don’t consider the separation of stakeholders’ and the developers’ concerns. Secondly, because it’s easier to write down everything in a document. But I have to say that this is wrong as SAD and design document (e.g. TSD) are built for different purposes and for different audiences (and in different phases if you are following a phase-based methodology such as RUP). If you put everything in a document, it’s as if while cooking dinner and you put the ingredients along with the utensils in a pot and boil them altogether!

A very good approach for looking at the problem from the stakeholder’s point of view is the 4+1 approach. At this model, scenarios (or Use Cases) are the base and we look at them from a logical view (what are the building blocks of the system), Process view (processes such as asynchronous operations), Development (aka Implementation) view and Physical (aka Deployment) view. There are also optional views such as Data View that you can use if you need to. Some of the views are technical and some of them are not, however they must match and there must be a consistency in the architecture so that technical views can cover business views (e.g. demonstration of a business process with a UML Activity Diagram and/or State Diagram).

I believe that each software project is like a spectrum that each stakeholder sees a limited part of it. The role of an architect is to see the entire spectrum. A good approach to do so (that I use a lot) is to include a business vision (this might not be a good term) in your SAD. It can be a bulleted list, a diagram or both, which shows what the application looks like from a business perspective. Label each part of the business vision with a letter or a number. Then add an architectural overview and then map it to the items of business vision indicating that which part of the architecture is meant to address which part of the business vision.

In a nutshell, Architecture is early design decisions, it is not the design.

What to put in an SAD?

There are a whole bunch of SAD templates on the Internet, such as the template offered by RUP. However the following items seem to be necessary for each architecture document:

  • Introduction. This can include Purpose, Glossary, Background of the project, Assumptions, References etc. I personally suggest that you explain that what kind of methodology you are following? This will avoid lots of debates, I promise!

It is very important to clear the scope of the document. Without a clear scope not only you will never know that when you are finished, you won’t be able to convince the stakeholder that the architecture is comprehensive enough and addresses all their needs.

  • Architectural goals and constraints: This can include the goals, as well as your business and architectural visions. Also explain the constraints (e.g. if the business has decided to develop the software system with Microsoft .NET, it is a constraint). I would suggest that you mention the components (or modules) of the system when you mention your architectural vision. For example say that it will include Identity Management, Reporting etc. And explain what your strategy to address them is. As this section is intended to help the business people to understand your architecture, try to include clear and well-organised diagrams.

A very important item that you want to mention is the architectural principles that you are following. This is even more important when the client organization maintains a set of architectural principles.

    • Quality of service requirements: Quality of service requirements address the quality attributes of the system, such as performance, scalability, security etc. These items must not be mentioned in a technical language and must not contain any details (e.g. the use of Microsoft Enterprise Library 5).
    • Use Case View: Views basically come from 4+1 model so if you follow a different model you might not have it. However, it is very important that you detect key scenarios (or Use Cases) and mention them in a high-level. Again, diagrams, such as Use Case Diagram, help.
    • Logical View: Logical view demonstrates the logical decomposition of the system, such as packages the build it. It will help the business people and the designers to understand the system better.
    • Process View: Use activity diagrams as well as state diagrams (if necessary) to explain the key processes of the system (e.g. the process of approving a leave request).
    • Deployment View: Deployment view demonstrates that how the system will work in a real production environment. I suggest that you put 2 types of diagrams: one (normal) human understandable diagram, such a Visio Diagram that shows the network, firewall, application server, database, etc.  Also a UML deployment diagram that demonstrates the nodes and dependencies. This will again helps the business and technical people have same understanding of the physical structure of the system.
    • Implementation View: This part is the most interesting section of the techies. I like to include the implementation options (e.g. Java and .NET) and provide a list of pros and cons for each of them. Again, technical pros and cons don’t make much sense to business people. They are mostly interested in Cost of Ownership and availability of the resources and so on.  If you suggest a technology or if it has already been selected, list the products and services that are needed on a production environment (e.g. IIS 7, SQL Server 2008).  Also it’ll be good to include a very high-level diagram of the system.

Also I like to explain the architectural patterns that I’m going to use. If you are including this section in the Implementation View, explain them enough so that a business person can quite understand what that pattern is for. For instance if you are using Lazy Loading patter, explain that what problem does it solve and why you are using it.

Needless to say that you have to also decide which kind of Architecture style you are suggesting, such as 3-Tier and N-Tier, Client-Server etc. Once you have declared that, explain the components of the system (Layers, Tiers and their relationships) by diagrams.

This part also must include your implementation strategy for addressing the Quality of Service Requirements, such as how will you address scaling out.

  • Data View: If the application is data centric, explain the overall solution of data management (never put a database design in this part), your backup and restore strategy as well as disaster recovery strategy.


Be iterative

It is suggested that the architecture (and in result the Software Architecture Document) be developed through two or more iterations. It’s impossible to build a comprehensive architecture document in one iteration as not only Architecture has an impact on the requirements, but also architecture  begins in an early stage and many of the scenarios are likely to change.

How to prove that?

Now that after doing lots of endeavor you have prepared your SAD, how will you prove it to the stakeholders? I assume that many of business people do not have any idea about the content and structure of an SAD and the amount of information that you must include in it.

A good approach is to prepare a presentation about the mission of the system, scope, goals, visions and your approach. Invite the stakeholders to a meeting and present the architecture to them and explain that how the architecture covers their business needs. If they are not satisfied, your architecture is very likely to be incomplete.


28 thoughts on “What is a Software Architecture Document and how would you build it?

  1. Well put and very true. It takes a great deal of creditation with experience before you should be allowed to even call oneself an architect and one should definitely NOT be allowed to switch titles like smarties.

  2. Hello superb website! Does running a blog like this take a great deal of work?
    I have virtually no expertise in computer programming but I
    was hoping to start my own blog in the near future.
    Anyway, should you have any recommendations or tips for new
    blog owners please share. I know this is off topic nevertheless I simply had to ask.
    Thanks a lot!

  3. Nice article. I think this is the best answer I have seen to the question: What does a Solution Architect do? Thanks.

  4. Nice blog right here! Additionally your website so much
    up very fast! What web host are you the use of? Can I am getting your affiliate
    hyperlink for your host? I wish my web site loaded up as fast as yours

  5. You really make it appear really easy along with your presentation however I in finding this topic to
    be actually one thing that I feel I’d never understand.

    It sort of feels too complicated and extremely huge for me.
    I am looking forward in your next publish, I will attempt to get the grasp of it!

  6. I’m impressed, I have to admit. Rarely do I encounter a blog that’s both equally educative and interesting, and
    without a doubt, you’ve hit the nail on the
    head. The problem is an issue that not enough men and women are speaking intelligently about.
    I am very happy I found this during my hunt for something concerning this.

  7. What i do not understood is actually how you’re now not actually much more neatly-favored than you might be now.
    You’re so intelligent. You recognize therefore significantly
    when it comes to this matter, made me in my view imagine it from a lot of numerous angles.
    Its like women and men aren’t involved except it’s one thing to accomplish
    with Woman gaga! Your personal stuffs outstanding. At all
    times maintain it up!

  8. It’s a shame you don’t have a donate button!
    I’d most certainly donate to this brilliant blog!
    I guess for now i’ll settle for book-marking and adding your RSS feed
    to my Google account. I look forward to new updates and will talk about this website with my Facebook group.
    Talk soon!

  9. Magnificent beat ! I wish to apprentice while you amend
    your web site, how could i subscribe for a blog website?
    The account helped me a acceptable deal. I had been tiny
    bit acquainted of this your broadcast provided bright clear concept

  10. I am no longer positive where you’re getting your information, however good topic.

    I must spend some time finding out more or working out more.
    Thanks for magnificent info I used to be on the lookout for
    this information for my mission.

  11. Thanks for a good read. Architecture is difficult to keep alive during a hectic project. It’s a matter of changing the culture. My company has developed a concept for that in agile work (google Talent Base Capo, but that is another story) Just wondering did you leave out Information Architect (- Viewpoint) on purpose? Sure, it can be seen as a dimension in each view:
    – Process view (conceptual IA, biz ontology, core taxonomies etc)
    – Logical view (LDM, class diagrams or smt similar for graph or RDF solutions)
    – Dev view (more detailed specs derived from LDM, data standards, interface definitions),
    – Physical view (how the IA is implemented, LDM became a proprietary graph DB structure or how RDF schema was installed and data populated in your triplet store etc.)

  12. Very good and informative article. I must point out that this interchangable use of terms such as ‘Solution Architect’, ‘Software Architect’ are also used in India. It is modified as the project manager /business wants it to be 🙂

Leave a Reply to Aref Cancel reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s