Architecture Document Template
building template
Published: 2022-08-11
Author: Hrishikesh Barman
Audience: Developers
Date: 6th August, 2022

This document describes how to build what we want to build. It should describe in what ways each component contributes to the requirements; solutions, strategies. trade-offs should be mentioned here.

This template is combination design docs at google + arc42

Introduction and Goals

  • A short intro in one paragraph

Requirements Overview

  • This can have subsection specific to the project
  • Links to other requirements documents. Balance redundancy wrt req. doc
  • These are also the architecture goals we want to achieve

Basic Usage

General functionality


  • Things that could reasonably be architecture goals, but are explicitly chosen not to be goals.

Quality Goals

  • Top3(Max5) quality goals for the architecture(not the project)
  • There can be more than one scenario with the same Quality goal
Quality Goal Scenario Priority


  • People or organizations that should know the about the architecture(not the project)


  • Any requirement that constrains software architects in their freedom of design and implementation decisions
  • Any requirement that constrains developers with their decision about the development process.

Context and Scope

  • Determines your system (scope) from all its communication partners (context)
  • Differentiate business context (domain specific i/o) from the technical context (channels, protocols, hardware).
  • Context diagrams

Business context

  • Specification of all communication partners(users, build-system, external resources etc.)
  • A table is helpful: Neighbour, Description

Technical/Deployment context

  • Technical interfaces(channels and i/o) linking your system to its environment.
  • A table is helpful: Node/Artifact/Component, Description

Solution Strategy

  • These decisions form the cornerstones for your architecture. Eg. If it’s going to be a microservice, you should mention it here.
  • They are the basis for many other detailed decisions or implementation rules.
  • top-level decomposition of the system, e.g. usage of some architectural pattern
  • decisions
    • technology decisions : why choose certain tech
    • organizational decisions: why choose certain process

Building block view

  • In analogy to a house this is the floor plan.
  • Describes the entire system at the abstract level without disclosing implementation details.
  • Describe the solution by listing services, modules, components, and their importance.
  • See the Form section here for the diagram accompanied by a description table.

Whitebox X

Building Block - Level 2

Building Block - Level 3

Runtime view

  • How do building blocks interact
  • No need to describe a large number of scenarios. document a representative selection.
    • Important use cases or features: how do building blocks execute them?
    • Interactions at critical external interfaces
    • Operation and administration: launch, start-up, stop
    • Error and exception scenarios
  • Can be written in any of:
    • Numbered list of steps (in natural language)
    • Activity diagrams or flow charts
    • Sequence diagrams
    • BPMN or EPCs (event process chains)
    • State machines

Deployment view

  • The technical infrastructure used to execute your system
  • The mapping of building blocks to that infrastructure elements.
  • Document development, production, test environment if exists
  • The highest level of deployment view should already be there in the context and scope section

Crosscutting concerns/concepts

  • Overall, principal regulations and solution ideas that are relevant in multiple parts
  • Any cross-cutting concerns such as security, privacy, and observability
  • See the diagram here

Domain model

Safety and security concerns

Under-the-hood ideas

Operational concepts

Development concepts


Overall planned timeline.