How to Document a Software Architecture

Architecture documentation is often a confusing topic in software development projects. At the heart of this confusion is the question “what to document”. This is not surprising since there is no widely accepted definition by the industry of what software architecture is. In my experience architecting software systems, I have focused on the commonalities that are evident in the various definitions set forth by authors and standards bodies. For the purpose of this discussion, software architecture can be viewed as the fundamental, high-level decomposition of the system components, how they are hosted and how they communicate with each other.

Deciding on what to document can be challenging because there is no universally accepted architecture documentation standard. Furthermore, it is often unclear what level of detail to include in the architecture document. The documentation template that I am presenting below is the result of my professional experience documenting architectures with various degrees of complexity. In practice I have found that the resulting architecture documents strike a good balance between usefulness and the cost to produce and maintain them. I have shared this template with many colleagues who have also found it useful. This template should be viewed as a starting point and modified to better meet your needs.

Software Architecture Document Template

1. Scope

[Document scope. This section should describe what type of information is included in this document so that readers may quickly determine whether the information they seek is likely to be in this document]

2. Background

[General function and purpose of the application]

3. Driving Requirements

[Significant requirements driving the chosen architecture]

4. Key Decisions

[Discussion of considered approaches and rationale for any significant architectural decision. This section should explain why the architecture is what it is]

5. Component View

[Graphical view of the main software modules, databases and external components that these modules interact with. Use boxes to represent modules and lines to represent interaction. Label these lines with communication protocol (e.g. HTTP, FTP, SQL, etc.). This section should help answer questions such as: what are the major executing components in the system? How do components interact? What are the major data stores? What external system does this application interact with?]

6. Deployment View

[Graphical view showing where the various components being developed are to be deployed. Describe this from the perspective of the Production system (i.e. use intended Production server names). If server names are not yet known use generic names. Depict a deployed component as a box inside of the enclosing server box. Also depict the hosting intranet and any intervening firewalls if there is any interaction with components outside of the intranet]

7. Security

[Discussion of security-related topics, as applicable (authentication, authorization, etc.)]