Software architecture document guidelines

Include information that is complementary to the code

Please see the Software Architecture for Developers book for the most up to date version of these guidelines.

The purpose of the software architecture document (SAD) is to provide information that is complementary to the code. At a high level, this might include:

Software architecture document guidelines

  1. An outline description of the software architecture, including major software components and their interactions.
  2. A common understanding of the drivers (requirements, constraints and principles) that influence the architecture.
  3. A description of the hardware and software platforms on which the system is built and deployed.
  4. Explicit justification of how the architecture satisfies the drivers.

See The code doesn't tell the whole story for the rationale on why software architecture documentation is necessary. As a guiding principle; the software architecture document should contain information that is complementary to the code and describe what the code itself doesn’t.

The following sections illustrate the content that should be included in a software architecture document and present information from several different views to take the most common stakeholders into account. It's worth noting that all of these views aren't necessarily required when taking into account factors such as project size, complexity, requirements, team, etc. If the information is available elsewhere, the software architecture document should make a reference to that source rather than repeating it (e.g. non-functional requirements may be stated in the requirements documentation and designs may be in separate design documents or a UML model). The SAD is a living document and may not contain all of the information listed here at any point in time.

  1. Context
  2. Functional View
  3. Process View
  4. Non-functional View
  5. Constraints
  6. Principles
  7. Logical View
  8. Interface View
  9. Design View
  10. Infrastructure View
  11. Deployment View
  12. Operational View
  13. Security View
  14. Data View
  15. Technology Selection
  16. Architecture Justification