A good explanation on what goes into software architecture document

from: http://stackoverflow.com/questions/4435792/what-should-you-put-into-an-architecture-specification

For me the key thing is to understand who the document is for: when would they use it? Why would they use it? Too many times it simply becomes a form-filling exercise for ticking boxes on some project plan.

I’m assuming you mean a software architecture document or solution architecture document – and not an enterprise strategy or something.

Remember too that there’re two things a typical architecture document will do:

  • Providing input into decisions to be made elsewhere: “this is our current thinking – would someone please decide whether to spend the big $$ for a DR site or not, etc”.
  • Recording decisions: particularly justifying your decisions.

In terms of both structure and key information to capture I’d recommend looking at different views of the system: logical, physical, data, security, and so on. A good starting point is the 4+1 model.

[Update:] One of the uses of such an artefact is Traceability – from requirements and design artefacts through to code artefacts; and while that might sound Waterfall orientated it actually applies (and works) for Agile based projects as well.

[Update:] Artefact doesn’t mean “Word Document”. The ToC example below is a supporting document / document based version of the system modelled in a UML modelling tool (SparxEA) which includes requirements as well. Sometimes you “have to” use a document, but I try to be as sparing as possible.

[Update:] The other good thing about a nice clearly laid out document is that it’s easier for new blood to get some understanding of what they are inheriting – especially if previous staff are not available.

The Software Engineering Institute at Carnegie Mellon has a bunch of information, and on the page below there’s a link to a template: http://www.sei.cmu.edu/architecture/tools/viewsandbeyond/
Bewared that it’s very comprehensive – not for the faint of heart (or lacking in time).

[Update:] Finally, here’s an example Table of Contents from a recent project. Despite the many sections the document’s not overly long (only about 35 pages, and a good portion of that is diagrams)


Sample table of content of a SA document

Table of Contents
1   Documentation Roadmap
1.1 Document & Version Information
1.1.1   Document Contributors
1.1.2   Referenced Documents
1.1.3   Reviewers   
1.1.4   Document Signoff    
1.2 Glossary of Terms   
1.3 Purpose and Scope of the SAD    
1.4 Stakeholder Representation  
2   Project Background  
2.1 Problem Background  
2.2 Solution Overview and Project Phases    
2.3 Solution Context    
2.3.1   Solution Usage  
2.4 Architectural Goals 
2.5 Constraints 
2.6 Considerations  
3   Register of Issues and Decisions    
3.1 Issues Register 
3.2 Decisions Register  
4   Overview of Key Views   
5   Functional View 
6   Logical Layers View 
7   Physical View   
7.1 Mapping of Logical and Physical Components  
7.2 Mapping of Logical Layers and Bespoke Packages  
7.3 Bespoke Physical Components 
7.4 Common  
7.5 Business Logic  
7.6 Data Provider Interfaces    
7.7 MS SQL Data Provider    
7.8 Data Repository 
7.9 External Data Services – Time Sheeting  
7.10    External Data Services - DLR    
7.11    UI - Flash  
7.12    FlourineFX  
7.13    UI - ASP.NET    
7.14    Model   
7.15    Login   
7.16    Mapping To Physical Components  
7.17    Solution Dependencies   
8   Solution Views  
8.1 Data View   23
8.1.1   Conceptual Data Model   
8.1.2   Physical Data Model 
8.2 Technology View 
8.2.1   Microsoft Windows Server    
8.2.2   Microsoft Internet Information Server   
8.2.3   Microsoft SQL Server    
8.2.4   Microsoft .Net Framework    
8.2.5   Microsoft ASP.NET   
8.2.6   Microsoft ASP.NET Role Membership Provider  
8.2.7   Dot Net Nuke (DNN)  
8.2.8   AntiXSS Library 
8.2.9   Microsoft Enterprise Libraries Application Logging Block   
8.2.10  Log4Net 
8.2.11  Fluorine    
8.2.12  Adobe Flash 
8.3 Security View   
8.3.1   Data Encryption – Data at Rest  
8.3.2   Data Encryption – Data in Flight    
8.3.3   Authentication  
8.3.4   Authorisation   
8.3.5   Non-Repudiation 
8.3.6   Cross-Site Scripting (XSS) and SQL Injection    
8.3.7   Other Security Concerns 
8.4 Infrastructure View 
8.5 Support View    
8.6 Enterprise Standards Compliance 
9   Design Patterns and Principles  
9.1 Dependency Inversion Principle  
9.2 Dependency Injection Pattern    
9.3 Factory Pattern 
9.4 Persistence Ignorance   
9.5 Dependency Injection    
Appendix – [legacy project name] Phase 1    
9.6 Bespoke Physical Components 

4+1 architecture view model (from: https://en.wikipedia.org/wiki/4%2B1_architectural_view_model)

4+1 is a view model designed by Philippe Kruchten for “describing the architecture of software-intensive systems, based on the use of multiple, concurrent views”.[1] The views are used to describe the system from the viewpoint of different stakeholders, such as end-users, developers and project managers. The four views of the model are logical, development, process and physical view. In addition selected use cases or scenarios are used to illustrate the architecture serving as the ‘plus one’ view. Hence the model contains 4+1 views:[1]

  • Development view: The development view illustrates a system from a programmer’s perspective and is concerned with software management. This view is also known as the implementation view. It uses the UML Component diagram to describe system components. UML Diagrams used to represent the development view include the Package diagram.[2]
  • Logical view: The logical view is concerned with the functionality that the system provides to end-users. UML diagrams used to represent the logical view include, class diagrams, and state diagrams.[2]
  • Physical view: The physical view depicts the system from a system engineer’s point of view. It is concerned with the topology of software components on the physical layer as well as the physical connections between these components. This view is also known as the deployment view. UML diagrams used to represent the physical view include the deployment diagram.[2]
  • Process view: The process view deals with the dynamic aspects of the system, explains the system processes and how they communicate, and focuses on the runtime behavior of the system. The process view addresses concurrency, distribution, integrators, performance, and scalability, etc. UML diagrams to represent process view include the activity diagram.[2]
  • Scenarios: The description of an architecture is illustrated using a small set of use cases, or scenarios, which become a fifth view. The scenarios describe sequences of interactions between objects and between processes. They are used to identify architectural elements and to illustrate and validate the architecture design. They also serve as a starting point for tests of an architecture prototype. This view is also known as the use case view.

The 4+1 view model is generic and is not restricted to any notation, tool or design method. Quoting Kruchten,

The “4+1” view model is rather “generic”: other notations and tools can be used, other design methods can be used, especially for the logical and process decompositions, but we have indicated the ones we have used with success.

— Philippe Kruchten, Architectural Blueprints—The “4+1” View Model of Software Architecture[1]