design-practice-repository

Summaries of artifacts, templates, practices, and techniques for agile architecting (DPR-mm) and service design (SDPR-nn).

DPR Git Pages Home — Activities Index

Activity/Technique: Architecture Modeling

also known as: Architecture Specification and Documentation

Context

Software architecture books such as “Software Architecture in Pratice” (@Bass:2012) or the German “Effektive Softwarearchitekturen” (@Starke:2015) teach us that any architecture design (and early solution strategy in particular) is about structure and technology.

The desire for structure can be met by the identification of candidate components and their continuous refinement, starting with “big” architectural decisions, for instance, about logical layers, Client/Server Cuts (CSCs), and architectural styles such as client/server and/or (micro-)service-oriented architectures.

Furthermore, technology concepts also have to be decided: middleware and frameworks such as component containers, communication protocols, and message exchange formats, as well as cluster and deployment managers (for instance, Spring Boot and Docker/Kubernetes running in a public cloud).

The arc42 website suggests a table format to capture early decisions; complementary to that, the overall architecture and selected parts and their dependencies and interactions should also be visualized (to accommodate the information needs of the different types of stakeholders, from project sponsors to DevOps personnel and auditors).

Goal and Purpose (When to Use and When not to Use)

As a software engineer performing architecture design work,

I want to capture my current understanding of the static and dynamic structure of the system under construction (in terms of its components and connectors), share it with peers and other stakeholders, and continuously evolve it

so that I can plan ahead (design and implementation work), manage risk, and trace the design back to architecturally significant requirements.

Instructions (Synopsis, Definition)

Model the architecture. Derive the level of abstraction, breadth, depth, and notation for any architectural model that you create from a set of stakeholder concerns and information needs caused by these concerns. Create one model/diagram per viewpoint (i.e., set of stakeholder concerns).

Architecture Modeling Steps and Viewpoints

For instance, four common modeling steps are:

  1. Create a system Context Diagram to visualize external dependencies (stakeholder: project manager; concern: scope control and risk management).
  2. Provide an Architecture Overview Diagram (aka container diagram) that captures the outcome of the early, “big” decisions made in the solution strategy (stakeholder: project sponsor, entire team; concern: joint understanding of technical approach to achieving project goals and stakeholder needs, project/iteration planning).
  3. Refine selected components that are technically challenging to design and implement in one or more Component Diagram(s) (stakeholder: architects, developers, maintainers; concern: support decision making, trace design and implementation progress, manage/mitigate technical risk during evolution and maintenance). You might want to capture the component design results in CRC Cards that explain responsibilities and collaborations of the boxes in architecture overviews and component diagrams. You also might want to complement these diagrams and cards with Component Interaction Diagrams (CIDs) that illustrate the dynamic behavior of the components.
  4. Show how and where logical components will be deployed to real or virtual hardware (stakeholder: DevOps personnel including database administrators, system managers, security specialists; concern: automation, cloud cost management, network configuration) in a Deployment Diagram.

A wide range of notations and tools to support these and other modeling tasks exist, from ad hoc and informal to systematic and full-fledged. Some of the choices include:

Popular viewpoint models are:

Example(s)

The component overview of the frontend-backend and service landscape at Lakeside Mutual, targeting architects and developers that want to orient themselves, was created with PlantUML:

Lakeside Mutual Component Overview

Page 4 of this presentation provides an example of an architecture overview diagram styled as an IRP. C4 examples are available publicly here. PlantUML extensions and examples can be found in The Hitchhiker’s Guide to PlantUML.

An arc42 FAQ provides examples of “big” solution strategy decisions worth capturing and visualizing. Section 5 of the arc42 template covers the building block view(s).

Benefits vs. Effort (Expected Benefits, Skill Levels)

“Agile Modeling” by Scott Ambler has a core practice called “Just Barely Good Enough Models and Documents” that covers cost vs. benefit of modeling (@Ambler:2002).

George Fairbanks sends similar messages in his book “Just Enough Software Architecture” (@Fairbanks:2010).

A variation of the “if in doubt leave it out” rule for DPR method adoption applies here:

Do not create a ‘big ball of model mud’; always have a distinct target audience with its information needs in mind when creating a model or a diagram. Base your in/out and naming decisions on the preferences and background of that particular audience.

Hints and Pitfalls to Avoid

Origins and Signs of Use

Modeling arguably has been there since the very beginnings of computer science and software engineering; most computer programs actually are models and abstractions of some parts of the real world.

By definition, models abstract from the modeled subject(s); so carefully decide what not to model. If the tips in the section “Hints and Pitfalls to Avoid” are followed, the use of architecture modeling and models is straightforward to spot. If not, you have a review finding and set of questions to ask.

Related Content

Application architects and anybody else involved in system design model architectures, using non-functional requirements and architectural decisions made as input. While modeling, new requirements and decisions required often are identified.

Non-functional requirements, for instance those captured in Quality Attribute Scenarios (QAS), provide essential input to this activity. Its output is documented in one or more instances of Context Diagram, Overview Diagram, Component Diagram(s), and Deployment Diagram. CRC Cards can be produced while modeling.

Practices and Techniques (Refinements, Guides)

More Information

Data Provenance

title: "Design Practice Repository (DPR): Architecture Modeling"
author: Olaf Zimmermann (ZIO)
date: "01, 27, 2023"
copyright: Copyright 2020-2023 Olaf Zimmermann. All rights reserved.
license: Creative Commons Attribution 4.0 International License