Skip to content
Tutorials Center
My learning

Topics

Lesson 47 of 50 ยท Projects

Project: An Architecture Review and ADR

Score three candidate designs against weighted quality scenarios, test how stable the winner is, then record the choice in a validated architecture decision record.

Choosing an architecture is one of the few software decisions that is both expensive to reverse and easy to make badly. Teams often pick whatever is fashionable, or whatever the loudest person likes, and discover the consequences a year later. An architecture review replaces opinion with a structured comparison: write down what the system must achieve, rate each candidate design against those goals, look for risks, and record the decision and its reasons.

In this project you review three designs for an invented online ticket shop, then write the result as an architecture decision record (ADR). You will use ideas from Architecture Styles and Architecture Decisions and Documentation. The tools are small JavaScript programs that run in your browser. They are stand-ins for a real review meeting: the scores are invented estimates, and a script can only add up numbers that people had to argue about first.

Step 1: state the quality scenarios

A review needs targets. "Fast" and "cheap" cannot be compared, but a quality attribute scenario with a measure can. Our ticket shop has five, each with a weight from 1 (nice to have) to 5 (critical) that the stakeholders agreed on:

ID Scenario Weight
Q1 Checkout finishes in under 800 ms for 95% of requests at peak (200 orders per second) 5
Q2 After a server crashes, service is back within 60 seconds 4
Q3 A new payment provider can be added in 10 working days 3
Q4 A new developer ships a small change in one week 3
Q5 The system runs within the budget of a three-person team 4

Notice that the scenarios already pull in different directions. Fast recovery and easy provider changes favor splitting the system into parts; a small team and quick onboarding favor keeping it together. That tension is the reason a review is needed.

Steps of a design review

Scenarios Write measurable goals with weights.
Candidates Sketch two or three real options.
Score Rate each option per scenario.
Record Write the ADR with the reasons.

The scores start the discussion. They do not end it.

1 / 2

Step 2: sketch the candidates

Draw each candidate at the container level, as in the C4 model, so the options are comparable. Here are the two extremes and the middle option.

flowchart LR
    subgraph A["A: Monolith"]
      A1["One app<br/>web + API + email"] --> A2[("Database")]
    end
    subgraph B["B: Modular monolith + queue"]
      B1["One app<br/>strict modules"] --> B2[("Database")]
      B1 --> B3["Queue"]
      B3 --> B4["Email worker"]
    end
    subgraph C["C: Microservices"]
      C1["Gateway"] --> C2["Orders"]
      C1 --> C3["Payments"]
      C1 --> C4["Tickets"]
      C2 --> C5[("Orders DB")]
      C3 --> C6[("Payments DB")]
      C4 --> C7[("Tickets DB")]
    end

Three candidates: one deployable app, one app with a queue for slow work, and several services with their own databases.

Each candidate has honest strengths. The plain monolith is cheapest and simplest. The modular monolith keeps one deployment but moves slow, failure-prone work (email) behind a queue. Microservices let parts scale and fail independently but cost a lot to operate.

Step 3: score the designs

For each design and scenario, the team agrees on a score from 1 (fails badly) to 5 (comfortably meets it). Real teams reach these numbers by discussing prototypes, past incidents and experience. Here they are invented.

The program computes a weighted total (score times weight, summed), converts it to a percentage of the best possible total, and flags a risk whenever a heavy scenario (weight 4 or more) scores 2 or lower for a design. A high total can hide a fatal weakness, so risks are reported separately from the total. It then repeats the calculation with one weight doubled to test the sensitivity of the result.

JS Score designs against weighted scenarios

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Read the output like a reviewer. The modular monolith leads with 76 points (80%) and has no risks. The plain monolith is close behind at 69 but carries risk Q2: it recovers poorly from a crash, and that scenario is heavy. Microservices score only 60 and carry risk Q5, because a three-person team cannot afford to run them. Doubling the weight of cost or of recovery changes the margins but not the winner, so the choice is robust to those disagreements. If a small change of weights flipped the winner, the right response would be to talk about the weights with the stakeholders, not to trust the script.

Try editing the scores. Raise the monolith's Q2 score to 4 (perhaps a managed platform restarts it quickly) and watch the gap close. Then ask the honest question: what evidence would justify that number? A score you cannot defend is just an opinion with a decimal point.

Step 4: probe the weak points

Before deciding, look at what the review exposed:

  • The winner's lowest scores. The modular monolith scores 4 everywhere. Nothing is a risk, but nothing is excellent. Is "good enough everywhere" what the business wants?
  • The heaviest scenario. Q1 (checkout speed) has weight 5 and every design scores 3 or 4. A load test of the real checkout path is worth more than any more arguing.
  • Reversibility. Can the team move from the modular monolith to services later? Clean module boundaries make that possible, which is why the winner's design says "strict modules".
  • Missing scenarios. Security, compliance and data privacy are absent from our list. A review is only as good as its scenarios, so ask what is missing before you finish.

Step 5: write the ADR

The decision is now written down so the next team does not have to repeat the debate. The ADR is stored as data so the program can check that it has the parts a good record needs (context, honest downsides, at least two alternatives, a trigger to revisit) and then render it as Markdown, ready for a docs/adr folder. The checker only tests the shape of the record; it cannot tell whether the decision is wise.

JS Validate and render an ADR

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The last line shows the checker catching an incomplete record: no downsides, only one alternative and no revisit trigger. Notice that the ADR links back to the scenario IDs (Q2, Q5), so a reader can trace each reason to a measurable goal. The status is proposed; after the team agrees it becomes accepted. If the decision changes in two years, a new ADR will supersede this one rather than editing it.

Step 6: make the review a habit

A review is not a one-off ceremony. Teams that keep the practice alive do a few simple things:

  1. Keep the scenarios in the repository and update them when requirements change.
  2. Add an ADR for every architecturally significant change, in the same pull request as the code.
  3. Revisit decisions when their revisit trigger fires, and record the outcome.
  4. Test the scariest scenario with a prototype before committing, as in risk-driven development.
  5. Write down accepted shortcuts as technical debt in the ADR.

Extension ideas

  • Add a scenario for security (for example, "a stolen session token stops working within 5 minutes") and re-score all three designs.
  • Add a fourth design, such as a serverless one, and see where it lands.
  • Make the program report the minimum weight change that would flip the winner.
  • Write a second ADR that supersedes this one when the daily order volume has grown tenfold.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does the review flag risks separately from the weighted total?

    A design can win on average while failing one heavy scenario badly. Flagging weight 4 or 5 scenarios that score 2 or lower keeps such weaknesses visible.
  2. 2. What does it mean that doubling a weight did not change the winner?

    Sensitivity analysis shows how much the outcome depends on the weights. A stable winner means disagreement about those weights does not change the decision.
  3. 3. Which part of an ADR lets a future reader decide whether the decision still applies?

    The context records the forces at the time, and the trigger states what change should make the team reconsider.
  4. 4. What is the main limit of a scoring script in an architecture review?

    The output is only as good as the scores and weights. Evidence from prototypes, load tests and experience is what makes a score defensible.
  5. 5. How should the team change a decision recorded in an accepted ADR?

    ADRs form a history. A superseding record keeps the old reasoning visible next to the new one.

Summary

  • An architecture review compares candidate designs against measurable, weighted quality scenarios instead of opinions.
  • Weighted totals rank the options; separate risk flags catch heavy scenarios that a design fails.
  • Sensitivity checks show whether the winner survives disagreement about priorities.
  • Scores are estimates: back the scariest ones with prototypes, load tests or past experience.
  • The decision goes into an ADR with context, honest consequences, alternatives and a revisit trigger, and links back to the scenarios.
  • Keep scenarios and ADRs in the repository and update them as the system and its goals change.

Next: Practice Exercises with Solutions.