As a Tech Lead or Solution Architect, you are often tasked to compile a document that defines the architecture of your project. In some cases, such as partnerships with third parties or tenders with government projects, the scope may have to cover the architecture of your company’s entire solution.

Compiling long and complex documents is often a daunting task. To give you a head start, I’m providing you with a basic overview of what such a document should look like and what it should contain.

Feel free to use the structure as-is, or add and remove extra sections as you see fit.

• Cover Page
• Table of Contents
• Versions and Approvals
• Overview
  • Purpose
  • In Scope
  • Out of Scope
• Glossary
• Roles and Responsibilities
• References
• Design Considerations
  • Assumptions
  • Constraints
  • Risks and Contingencies
• Technical Architecture
  • System Overview
  • Technical Requirements
  • Data Access
  • Data Management
  • Testing
  • Privacy

Cover Page

Your cover page should include the title of your project and/or company, as well as your corporate branding (headers and footers) and the title "System Architecture Definition", or something similar.

Table of Contents

I don’t believe I need to go into too much detail here. Simply make use of the built-in auto-generation tools from Google Docs or MS Word.

Version and Approvals

Include a page with the following two tables: “Version Control” and “Approvals”.

The Version Control table contains the version number, the changes made in that version, the author of the changes, as well as the date the changes were made.

The Approvals table contains the names of the approvers, their roles, their signatures, and the date it was approved.

1. Overview

1.1 Purpose

This section should provide a high-level description of the purpose of this document. This may include how the new system will meet the intended goals and objectives of the organisation and/or project. Touch on the following points in this section of your document:

• A description of the system
• The logical architecture of software (top-level components and interactions)
• The physical architecture of the hardware
• The justification of technical choices made

1.2 In Scope

Describe all areas of the project that are in-scope of this document.

1.3 Out of Scope

Similarly, list all areas that are considered out-of-scope of this document.

2. Glossary

Create a table with terms and abbreviations and include their meaning. See below for an example.

3. Roles and Responsibilities

A “roles and responsibilities” section may be necessary to clarify who performs each task within the system.

4. References

List the references (internal and external) that guided the system design e.g. organisational standards, industry standards, meeting minutes, etc. Do not include too much detail since the items on the list can be referred to individually if more detail is needed.

5. Design Considerations

5.1 Assumptions

List all major assumptions made prior to or during business requirements gathering and documentation, e.g. end-user characteristics, system requirements and possible and/or probable changes in functionality.

5.2 Constraints

Define the constraints associated with the system design. These may include hardware, software, business constraints, organizational/industry standards, etc. Also include how the constraints affect or limit the system design.

5.3 Risks and Contingencies

Identify any risks that may impact delivery. For each risk, propose mitigation strategies, as well as backup mechanisms in place in case of extended downtime.

6. Technical Architecture

6.1 System Overview

Provide a high-level diagram of the architecture of the system. Describe the components as well as how their interactions will achieve the required results. Include a typical workflow of the system if desired. Additionally, include users on the diagram if this will aid the description of the system.

Source: https://www.devteam.space/blog/microservice-architecture-examples-and-diagram/

6.2 Technical Requirements

List all the hardware, software and external dependencies required by the system.

6.3 Data Access

Describe the data access layer design including the ORM, security considerations (e.g. authentication), auditing and encryption.

6.4. Data Management

Cover elements such as data migration, backups and archiving.

6.5 Testing

Define which tests will be developed and/or performed to ensure the solution is stable, e.g. unit tests, automated UI tests, load tests, penetration tests, etc.

6.6. Privacy

Describe the information that will be stored in the system, and whether any information is PII (personally identifiable information).

Also, identify data that needs to be redacted/scrambled in order to legally send backups to external vendors for further processing and system enhancements.

And that’s it! I hope this guide proves to be thorough, yet concise and simple to follow. Let me know in the comments section if you have any suggestions.