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

• joelparkerhenderson/architecture-decision-record
• A Simple Framework for Architectural Decisions

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

Non-goals

• 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

Stakeholders

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

Constraints

• 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

Milestones

Overall planned timeline.