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 Quality Goal Scenario Priority Stability Reliability Security Maintainability Efficiency Compatibility 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.