What should you add to the architecture specification?

Question

I am currently reviewing several document templates for my company. One thing we never had is a formal specification of architecture, so I'm starting to put it together.

What things do you invest in your architecture specifications? Feel free to copy and paste the table of contents - that would be helpful. Are there any good templates already available on the Internet?

Answer 1

I agree with the feeling of Asaphos; fortunately, it is not possible to make useful / practical architectural documentation - just not accepted.

The main thing for me is to understand for whom the document is intended: when will they use it? Why would they use this? Too many times, it just becomes an exercise to fill out a ticking box form on some project plan.

I assume that you are referring to a software architecture document or a solution architecture document, not an enterprise strategy or something like that.

Remember also that there are two things that a typical architecture document will do:

• Contributing to decisions that need to be made elsewhere: "this is our current thinking - someone, please, decide whether to spend big $$ on a DR site or not, etc."
• Registration decisions: especially the rationale for your decisions.

From the point of view of both the structure and the key information for capture, I would recommend looking at the various representations of the system: logical, physical, data, security, etc. A good starting point is the 4 + 1 model .

[Update:] One of the uses of the artifact is Traceability - from requirements and design of artifacts to code artifacts; and although it may seem that Waterfall is oriented, it actually applies (and works) to Agile-based projects.

[Update:] Artifact does not mean "Word Document". The following is an example of ToC - this is a supporting document / document-based version modeled in the UML Modeling Tool (SparxEA), which also includes requirements. Sometimes you “should” use a document, but I try to be as economical as possible.

[Update:] Another good thing about a good clear document is that for new blood it is easier to understand what they inherit, especially if the previous staff is not available.

The Carnegie Mellon Institute of Software Engineering has a ton of information, and there is a link to a template on the page below: http://www.sei.cmu.edu/architecture/tools/viewsandbeyond/
Ill, that it is very comprehensive - not for the faint of heart (or not enough time).

[Update:] Finally, here is an example of content from a recent project. Despite the fact that in many sections the document is not too long (only about 35 pages, and most of this is diagrams).

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 8.2.9.1 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 

Answer 2

In my personal opinion, I find the following topics useful in defining Software Documentation :

• Introduction (document objectives)
• Context diagram (application purpose)
• Hardware requirements (memory and processor requirements)
• Software requirements (operating systems, database server, frameworks, libraries)
• Operational model (business operations, process sheets)
• Physical architecture model (physical location, servers, DMZ, firewall)
• Application architecture architecture (application layers, services, components, UML diagrams)
• Database Model (UML-PDM; Tables, Sps, Views, Triggers)
• Security Model (authentication, authorization, personalization, hashing)
• GUI Model (screens, usage diagrams, general controls)
• Data Dictionary (Excel format)

Take a look at these Microsoft Application Architecture Guide :

• Application Architecture Guide 2.0
• Application Architecture for .NET: Designing Applications and Services

Answer 3

My typical ingredients for an architecture specification:

• Static system structure
  • Overview
  • Components (for each component: functions, technology, perseverance)
  • Interfaces (internal and external, machine and machine and user interfaces)
• Dynamic behavior
  • Business processes (e.g. use cases)
  • Display of business processes in the system structure (for example, sequence diagrams)
• Deployment
  • HW Review
  • Network Overview
  • Mapping software components to hardware

See also 4 + 1 Model .

Answer 4

IEEE has many standards to address this issue. For example, IEEE 1016, it defines the organizational structure of a software description. http://en.wikipedia.org/wiki/Software_Design_Description

The document should contain at least the following chapters

• INTRODUCTION
  • Design Overview
  • Requirement Tracking Matrix
• SYSTEM ARCHITECTURAL DESIGN
  • Selected System Architecture
  • Discussion of alternative designs
  • System Interface Description
• DETAILED DESCRIPTION OF COMPONENTS
  • Component n
  • Component n + 1
• USER INTERFACE
  • User Interface Description
    • Screen image
    • Objects and Actions
• ADDITIONAL MATERIAL

Answer 5

The architecture should provide leadership to developers in a way that avoids integration and maintenance issues. More specifically, the architecture must identify things such as approved operating systems, approved development languages, approved storage systems, approved communication protocols, coding methods, testing frameworks, source control, user acceptance procedures and product release procedures, separation of problems, maintenance procedures and security. In most cases, this is a living document, and sections are added and refined as technology improves. Since each company is unique, a copy of the guide will only be useful for ideas on what to include. Based on the answers of others, you already have a number of great ideas that you can use.

Answer 6

"Architecture Specification" will be a very limited term. "Architectural documentation" would be the right term.

The architect’s goal is to have a system design to satisfy the non-functional requirements (NFR) of the QoS (Quality of Service) attributes (e.g., scalability, availability, performance, reliability, security, extensibility, maintainability, manageability, etc.). which supports core business functions.

You will need to document the QoS attributes that are important to your system and what design options you made to implement them. These Qos attributes are interrelated, and you may have to make some transactions, so you should mention these trade-offs with the corresponding arguments.

To achieve QoS, you will systematically decompose your system by distribution, levels (level / layer), impact, functionality, community, cohesion and cohesion, volatility, configurability, etc. This can be considered as "Specificity of architecture", followed by developers to implement various components in the system.

How a system is deployed also affects QoS. You will need to document the network and hardware infrastructure and how the applications will be deployed on this equipment. How to increase system capacity (vertically / horizontally) or increase redundancy.

Answer 7

This discussion is:

At RUP: What roles are RUP responsible for creating a software architecture document?

provides this template :

http://www.ts.mah.se/RUP/RationalUnifiedProcess/webtmpl/templates/a_and_d/rup_sad.htm

and this overview of the SAD document in RUP:

http://www.ts.mah.se/RUP/RationalUnifiedProcess/process/artifact/ar_sadoc.htm

Answer 8

Architecture features provide a high level of system visibility. This helps the developer to get an overall picture of the system and helps to visualize the interaction of various subsystems. As a rule, architecture covers many product releases, so it should try to cover maintainability, flexibility for expected requirements.

I think it is important to provide sufficient coverage of the following topics in architecture specifications

• Requirements
• Usecases
• Architectural block diagram
• Subsystems and Interfaces
• Security / Reliability / Availability
• Testing Strategies

Answer 9

Good read: https://www.amazon.com/Documenting-Software-Architectures-Views-Beyond/dp/0321552687

You should write your architectural documentation with your interested parties (e.g. developers, customers). The views and content depend on what is needed for the interested parties. Therefore, the contents of your architecture may vary from project to project.