Reviewing Software Architectures

Process · Chapter 12

Why review architectures

Reviewing an architecture determines whether functional requirements and quality attribute scenarios can be satisfied. Finding and fixing mistakes early greatly reduces the cost of defects and avoids rework. Reviews also apply when acquiring software or comparing architectures.

Four evaluation methods covered: SAAM, ATAM, ADR, and ARID — all scenario-based.

Quality attribute scenarios (the shared building block)

A scenario describes an interaction between a source and the system, representing a use or expected quality. A quality attribute scenario has six parts:

Part	Meaning
Source of stimulus	Entity generating the stimulus (stakeholder, another system)
Stimulus	Condition requiring a system response
Artifact	The software stimulated (part, whole, or multiple systems)
Environment	Conditions under which the stimulus occurs
Response	Activity that happens when the stimulus arrives
Response measure	How the response is measured, so it can be tested against requirements

SAAM — Software Architecture Analysis Method

One of the first documented evaluation methods; originally for modifiability, later extended to reliability, portability, extensibility, performance. Six steps:

1. Develop scenarios — derive from requirements and quality attributes; brainstorm with diverse stakeholders; iterate.
2. Describe the architecture — architect presents it using documentation whose notations everyone understands.
3. Classify and prioritize scenarios — direct (no change needed) vs indirect (requires modification); prioritize by voting.
4. Evaluate scenarios — demonstrate direct scenarios; for indirect ones, identify required changes and estimate effort.
5. Assess scenario interaction — multiple unrelated scenarios touching the same component signals poor design: low cohesion / tight coupling, possibly needing to split the component. (See orthogonality.)
6. Create an overall evaluation — decide whether the architecture is viable as-is or must be modified.

ATAM — Architecture Tradeoff Analysis Method

Successor to SAAM; focuses on design decisions and quality attribute tradeoffs.

Participant roles

• Evaluation team (ideally external): team leader (organizes, ensures final report), evaluation leader (runs the review), scenario scribe (whiteboard notes), proceedings scribe (electronic notes), questioner (raises quality-attribute issues).
• Project decision makers — authority to change the software and assign resources (sponsors, project managers, architects).
• Stakeholders — anyone with a vested interest.

Four phases

• Phase 0 – Partnership & preparation: agree on logistics/attendees; team studies the architecture docs and sets expectations for Phase 1.
• Phase 1 – Evaluation (with decision makers): (1) present the ATAM, (2) present business drivers, (3) present the architecture, (4) identify architectural approaches (patterns, reference architectures, tactics, external software), (5) generate the quality attribute utility tree, (6) analyze architectural approaches.
• Phase 2 – Evaluation continued (adds stakeholders, ~1 week later): (7) brainstorm and prioritize scenarios by voting, (8) analyze architectural approaches, (9) present results tying risks back to business drivers.
• Phase 3 – Follow-up: produce and deliver the final report (~1 week) to whoever commissioned the review.

Utility tree

A prioritized structure: quality attribute → subcategory → quality attribute scenario. Example: Security → Authentication (“passwords hashed with bcrypt”) and Confidentiality (“a customer-service rep sees only the last four digits of an SSN” — a role-based access control rule). Decision makers prioritize scenarios by voting; comparing the utility-tree list against the stakeholder-generated list checks alignment — divergence uncovers overlooked scenarios and risk.

ADR — Active Design Review

Best for in-progress designs, reviewing individual sections rather than the whole architecture at once. Premise: reviewing an entire architecture at once is too much information and too little time, so no part gets a complete evaluation and there is too little reviewer/designer interaction. ADR uses questionnaires to keep reviewers actively engaged. Five steps:

1. Prepare the documentation — include assumptions (what won’t change) and incorrect-usage assumptions.
2. Identify the specialized reviews — pin each reviewer to specific properties/quality attributes.
3. Identify the reviewers — seek diverse perspectives (developers off this part, staff from other projects, users, non-technical specialists, external reviewers).
4. Design the questionnaires — open, active phrasing (e.g., “write pseudocode using this part”) to force real engagement with the docs.
5. Conduct the review — present the module, complete questionnaires, then meet with designers to clarify and, if needed, modify the artifact.

ARID — Active Reviews of Intermediate Designs

A hybrid of ADR and ATAM: takes ADR’s focus on in-progress designs and active participation, plus ATAM’s focus on quality attribute scenarios. Goal: assess viability and surface errors/inadequacies.

Participant roles

ARID review team (facilitator, scribe, questioners), the software architect/lead designer (owns and presents the design), and the reviewers (stakeholders with a vested interest).

Two phases, nine steps

• Phase 1 – Pre-meeting (architect + facilitator): (1) identify reviewers, (2) prepare the design presentation (practice + feedback), (3) prepare seed scenarios, (4) prepare for the review meeting (materials, logistics, invitations).
• Phase 2 – Review meeting: (5) present the ARID method, (6) present the design — avoid rationale/alternative debates, encourage factual clarification and issue-spotting, scribe captures issues, (7) brainstorm and prioritize scenarios (seed + new, voted) which define what makes the architecture usable, (8) perform the review — reviewers test scenarios, writing real or pseudocode, (9) present conclusions on suitability, feeding refactoring.

Method selection at a glance

Method	Best when	Distinctive focus
SAAM	Any stage; comparing/modifiability	Simple 6-step scenario evaluation
ATAM	Fuller architecture	Decisions, tradeoffs, risks vs business drivers
ADR	In-progress, section-by-section	Questionnaire-driven active review
ARID	In-progress, need usability check	ADR participation + ATAM scenarios

Citations

• Software Architect’s Handbook (Packt, 2018), Ch.12 “Reviewing software architectures”, pp. 957-992.