🖼️ See the drawing + lab 🏠 Course home 🌿 Branch on GitHub ✏️ View source

🖼️ आकृती आणि labThe drawing + lab पूर्ण पानावर उघडा ↗Open full page ↗

📓 धडा 11 — ADRs आणि trade-off analysis: मुख्याध्यापिकेची नोंदवही

📍 तुम्ही इथे आहात: 12 पैकी धडा 11 · मागचा: lesson-10-c4 · पुढचा: lesson-12-evolution

📦 या ब्रँचमध्ये काय आहे

धडे 01–10, आणि का. Architecture decision record (ADR) एक निर्णय लिहून ठेवते — त्याचा संदर्भ, केलेली निवड आणि परिणाम — म्हणजे पुढच्या व्यक्तीला अंदाज लावावा लागत नाही. तो लिहिण्याआधी, एक हलके trade-off analysis: weights असलेले quality-attribute scenarios, प्रत्येक पर्यायाला गुण, आणि उत्तर उलटायला weights किती बदलावे लागतील याची तपासणी. Lab याला ATAM-lite म्हणते: SEI च्या Architecture Tradeoff Analysis Method पासून प्रेरित एक छोटा गुणांकन सराव — ती method स्वतः नव्हे. atam(), flip_weight() आणि adr() arch/models.py मध्ये, adr arch/demo.py मध्ये. System Design शाळेचा cost, trade-offs आणि ADRs वरचा धडा एक cost model जोडतो; इथे आपण रचनेच्या निर्णयावर लक्ष देतो.

🧒 5 वर्षांच्या मुलाला समजावल्यासारखे

अनेक वर्षांपूर्वी कोणीतरी ठरवले की शाळेला चार नव्हे तर एकच इमारत असेल. आज ऐश्वर्या विचारते: "का? चार इमारती किती छान झाल्या असत्या!" कोणालाच आठवत नाही. 🤷‍♀️ म्हणून शाळेत तोच लांबलचक वाद पुन्हा सुरू होतो.

कतरिना मुख्याध्यापिकेच्या कार्यालयात एक नोंदवही 📓 सुरू करते. प्रत्येक मोठ्या निर्णयासाठी ती एक पान लिहिते:

काय चालले होते — "चार विभाग, तीन बांधकाम करणारे, निकालाचा दिवस खूप गर्दीचा."
आम्ही काय ठरवले — "एकच इमारत, विभागांमध्ये भिंती."
त्याचा अर्थ काय — "सगळ्यांसाठी एकच fire alarm; अजून कोणताही विभाग आपल्या स्वतःच्या दिवशी पुन्हा बांधकाम करू शकत नाही."

आणि ठरवण्याआधी तिने एक छोटा तक्ता केला: सर्वात महत्त्वाचे काय, आणि प्रत्येक योजना किती चांगली ठरते. तिने हेही लिहून ठेवले: "आपल्या स्वतःच्या दिवशी पुन्हा बांधकाम करणे कधी खूप महत्त्वाचे झाले, तर हे पुन्हा पाहा." आता वाद पाच मिनिटांत संपतो: पान वाचा.

🗺️ आकृती

flowchart LR
    s["📋 5 scenarios, weights 1–3<br/>modifiability 3 · operability 3 · performance 2<br/>deployability 1 · scalability 1"]
    s --> mm["🏫 modular monolith → 42"]
    s --> m["🏚️ monolith → 35"]
    s --> ms["🏘️ microservices → 34"]
    mm --> adr["📓 ADR-0007: A modular monolith<br/>Status: Accepted"]
    flip["⚖️ deployability weight 4 → microservices 49 vs 48"] -.->|"revisit when"| adr

🗺️ काढलेली आकृती + एक lab: https://school-edh.pages.dev/software-architecture/lesson-diagrams.html#l11

❓ काय

Architecture decision record (ADR) — एका महत्त्वाच्या निर्णयासाठी छोटी text file. Michael Nygard यांचा 2011 चा format: Title, Status, Context, Decision, Consequences. क्रमांक दिलेले, repo मध्ये ठेवलेले, कधीच delete न केलेले: बदललेल्या निर्णयासाठी एक नवीन ADR येतो जो जुन्याला supersede करतो.
Status — proposed, accepted, deprecated, किंवा ADR-NNNN ने superseded.
Consequences — चांगले आणि वाईट, सगळे. फक्त चांगले परिणाम असलेला ADR म्हणजे जाहिरात.
Quality attribute scenario — एका -ility साठी (धडा 01) test करता येणारे वाक्य: stimulus, environment, response, measure — "निकालाच्या दिवशी report card < 300 ms मध्ये".
ATAM (Architecture Tradeoff Analysis Method) — Software Engineering Institute कडून (Rick Kazman, Mark Klein, Paul Clements आणि इतर, साधारण 2000): stakeholders सोबतची एक रचनाबद्ध workshop. ती प्राधान्यक्रम दिलेल्या scenarios चे utility tree बनवते, त्यांच्याविरुद्ध architecture तपासते, आणि risks, non-risks, sensitivity points (असा design गुणधर्म ज्यावर एखाद्या quality चा प्रतिसाद निर्णायकपणे अवलंबून असतो) आणि trade-off points (एकापेक्षा जास्त qualities वर, विरुद्ध दिशांनी परिणाम करणारा गुणधर्म) नोंदवते.
ATAM-lite (हे lab) — weighted गुणांकन: प्रत्येक scenario साठी weight × score, बेरीज करून. आणि एक weight check: विजेता उलटवणारा सर्वात छोटा weight बदल. ही decision-analysis मधली sensitivity तपासणी आहे, ATAM चा "sensitivity point" नव्हे. Scores म्हणजे टीमचा अंदाज — गणित फक्त तो अंदाज दिसणारा आणि चर्चा करता येणारा बनवते.

🤔 का

कारण सर्वात महाग निर्णय (धडा 01) हेच असे निर्णय असतात ज्यांची कारणे सर्वात लवकर विसरली जातात. "का" शिवाय, टीम्स एकतर निर्णयाला कधीच हात लावत नाहीत (भीती) किंवा तो कशाचे रक्षण करत होता हे न कळता उलटवतात (उलथापालथ). Weighted तक्ता टीमला निवड करण्याआधी आपल्याला काय मौल्यवान वाटते ते सांगायला भाग पाडतो, आणि weight check निर्णय कधी पुन्हा उघडावा हे सांगतो — त्यामुळे "एक दिवस आपल्याला microservices लागतील कदाचित" याचे रूपांतर ठोस trigger मध्ये होते.

🔧 कसे (या repo मध्ये)

arch/models.py मधल्या SCENARIOS मध्ये 1–3 weights असलेले पाच scenarios आहेत; OPTIONS मध्ये प्रत्येक पर्यायाचे 1–5 scores त्याच क्रमाने आहेत. atam(options, scenarios, weights) weight × score ची बेरीज करते. flip_weight(attr, rival) एका attribute चे weight 1 पासून वर वाढवते आणि ज्या पहिल्या weight ला rival ला सर्वाधिक गुण मिळतात ते परत करते (किंवा None). adr(number, title, context, decision, consequences) Nygard शैलीचा ADR Markdown मध्ये परत करते.

🧪 करून पाहा

python3 arch/demo.py adr
python3 - <<'EOF'
import sys; sys.path.insert(0, "arch"); from models import atam, SCENARIOS, adr
base = [s[2] for s in SCENARIOS]
for w in (1, 2, 3, 4, 5):
    t = atam(weights=base[:3] + [w] + base[4:])
    print(f"deployability weight {w}: " + " · ".join(f"{o} {v}" for o, v in t.items()) + f" → {max(t, key=t.get)}")
print(adr(7, "A modular monolith for the school app", "4 departments, a team of 3, results-day peaks.",
          "One deployable, departments as modules, boundaries checked in CI.", ["one transaction per request", "no independent deploys yet"]))
EOF

✅ तपासा — तुम्हाला काय दिसायला हवे

adr हे छापते:

   modular monolith [4, 5, 5, 2, 3] → 42
   monolith         [2, 5, 5, 1, 3] → 35
   microservices    [4, 2, 3, 5, 5] → 34
   weights matter: microservices would win if deployability weighed 4 (not 1), or scalability 6 (not 1)

तुमचा snippet हे छापतो:

deployability weight 1: monolith 35 · modular monolith 42 · microservices 34 → modular monolith
deployability weight 2: monolith 36 · modular monolith 44 · microservices 39 → modular monolith
deployability weight 3: monolith 37 · modular monolith 46 · microservices 44 → modular monolith
deployability weight 4: monolith 38 · modular monolith 48 · microservices 49 → microservices
deployability weight 5: monolith 39 · modular monolith 50 · microservices 54 → microservices
# ADR-0007: A modular monolith for the school app

Status: Accepted

## Context
4 departments, a team of 3, results-day peaks.

## Decision
One deployable, departments as modules, boundaries checked in CI.

## Consequences
- one transaction per request
- no independent deploys yet

🏁 तुम्ही आत्ताच काय सिद्ध केले

आजच्या weights नुसार modular monolith स्पष्टपणे जिंकतो (42 विरुद्ध 35 विरुद्ध 34). पण उत्तर ठरलेले नाही: इतर विभागांशिवाय एकच विभाग release करण्याचे मूल्य 1 ऐवजी 4 झाले, तर microservices फक्त एका गुणाने जिंकतील (49 विरुद्ध 48). यातून दोन गोष्टी कळतात. पहिली, निर्णय बऱ्यापैकी भक्कम आहे — तो उलटण्याआधी deployability, modifiability पेक्षा जास्त महत्त्वाची व्हायला हवी. दुसरी, कशावर लक्ष ठेवायचे ते कळते: ADR चे consequences सांगतात "deployability weight 4 झाले तर पुन्हा पाहा", म्हणून भविष्यातील टीमला आवडी-निवडीवर पुन्हा वाद घालण्याऐवजी trigger माहीत असतो. यापैकी कोणत्याही weight ला monolith कधीच जिंकत नाही — विभागांमधल्या भिंती (modifiability 4 विरुद्ध 2) ठेवण्यासारख्या आहेत.

⚠️ नेहमीच्या चुका

आधीच घेतलेल्या निर्णयाचे समर्थन करण्यासाठी नंतर लिहिलेले ADRs
प्रत्येक क्षुल्लक निवडीसाठी एक ADR — मग त्यातले कोणीच काहीच वाचत नाही
accepted ADR supersede करण्याऐवजी edit करणे — इतिहास हरवतो
एकाच व्यक्तीने, किंवा उत्तर माहीत झाल्यावर निवडलेले scores आणि weights
बेरजेवर दोन दशांश स्थानांपर्यंत विश्वास ठेवणे — scores म्हणजे अंदाज; अंतरे आणि flip points पाहा
"revisit when" नाही — निर्णय कधीच सुरक्षितपणे पुन्हा उघडता येत नाही

🏭 प्रत्यक्ष वापरात

खऱ्या project वर — Nat Pryce यांचे adr-tools ADRs क्रमांक दिलेल्या Markdown files म्हणून ठेवते:

adr init docs/architecture/decisions          # creates 0001-record-architecture-decisions.md
adr new A modular monolith for the school app # 0002-a-modular-monolith-for-the-school-app.md
adr new -s 2 Split grades into its own service   # a new ADR that supersedes 0002
adr list

Nygard शैलीचा ADR, repo मधली file म्हणून:

# 7. A modular monolith for the school app

Date: 2026-09-01

## Status
Accepted

## Context
Four departments (admissions, grades, fees, timetable), a team of three, a 20× spike on
results day. Scored: modular monolith 42, monolith 35, microservices 34.

## Decision
One deployable. Departments are top-level packages. import-linter contracts keep them apart.

## Consequences
- One database transaction per request; no sagas.
- No independent deploys: a fees change redeploys grades.
- Revisit if independent deployability becomes as important as modifiability.

इतर लोकप्रिय templates म्हणजे MADR (Markdown Any Decision Records), जो फायदे-तोट्यांसह "considered options" जोडतो, आणि Y-statements ("In the context of …, facing …, we decided … to achieve …, accepting …").

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: तुमची टीम ज्या निर्णयावर सर्वात जास्त वेळा पुन्हा वाद घालते तो शोधा. या आठवड्यात त्याचा ADR लिहा, पुन्हा पाहण्याच्या trigger सह — आणि तो ज्या code ला लागू होतो तिथून त्याची link द्या.

⏭️ पुढे

निर्णय घेतले, नियम तपासले, चित्रे खरी. पण शाळा प्रत्येक term ला वाढते. मुले आत असताना इमारत कशी बदलायची? Evolving architecture — आणि संपूर्ण चित्र.

git checkout lesson-12-evolution

📓 Lesson 11 — ADRs and trade-off analysis: the principal's logbook

📍 You are here: Lesson 11 of 12 · Previous: lesson-10-c4 · Next: lesson-12-evolution

📦 What's in this branch

Lessons 01–10, plus the why. An architecture decision record (ADR) writes down one decision — its context, the choice and the consequences — so the next person does not have to guess. Before writing it, a light trade-off analysis: quality-attribute scenarios with weights, each option scored, and a check of how much the weights would have to change to flip the answer. The lab calls it ATAM-lite: a small scoring exercise inspired by the SEI's Architecture Tradeoff Analysis Method — not the method itself. atam(), flip_weight() and adr() in arch/models.py, adr in arch/demo.py. The System Design school's lesson on cost, trade-offs and ADRs adds a cost model; here we focus on the structure decision.

🧒 Explain like I'm 5

Years ago, someone decided the school would have one building, not four. Today, Aishwarya asks: "Why? Four buildings would be so nice!" Nobody remembers. 🤷‍♀️ So the school has the same long argument all over again.

Katrina starts a logbook 📓 in the principal's office. For every big decision she writes one page:

What was going on — "four departments, three builders, results day is very busy."
What we decided — "one building, with walls between departments."
What that means — "one fire alarm for everyone; no department can rebuild on its own day yet."

And before deciding, she made a small table: what matters most, and how well each plan does. She even wrote down: "if rebuilding on your own day ever becomes very important, look at this again." Now the argument takes five minutes: read the page.

🗺️ Diagram

flowchart LR
    s["📋 5 scenarios, weights 1–3<br/>modifiability 3 · operability 3 · performance 2<br/>deployability 1 · scalability 1"]
    s --> mm["🏫 modular monolith → 42"]
    s --> m["🏚️ monolith → 35"]
    s --> ms["🏘️ microservices → 34"]
    mm --> adr["📓 ADR-0007: A modular monolith<br/>Status: Accepted"]
    flip["⚖️ deployability weight 4 → microservices 49 vs 48"] -.->|"revisit when"| adr

🗺️ Drawn version + a lab: https://school-edh.pages.dev/software-architecture/lesson-diagrams.html#l11

❓ What

Architecture decision record (ADR) — a short text file for one significant decision. Michael Nygard's 2011 format: Title, Status, Context, Decision, Consequences. Numbered, kept in the repo, never deleted: a changed decision gets a new ADR that supersedes the old one.
Status — proposed, accepted, deprecated, or superseded by ADR-NNNN.
Consequences — all of them, good and bad. An ADR with only good consequences is an advertisement.
Quality attribute scenario — a testable sentence for one -ility (lesson 01): stimulus, environment, response, measure — "a report card in < 300 ms on results day".
ATAM (Architecture Tradeoff Analysis Method) — from the Software Engineering Institute (Rick Kazman, Mark Klein, Paul Clements and others, around 2000): a structured workshop with stakeholders. It builds a utility tree of prioritised scenarios, walks the architecture against them, and records risks, non-risks, sensitivity points (a design property that one quality response depends on critically) and trade-off points (a property that affects more than one quality, in opposite directions).
ATAM-lite (this lab) — weighted scoring: weight × score per scenario, summed. Plus a weight check: the smallest weight change that would flip the winner. This is a decision-analysis sensitivity check, not ATAM's "sensitivity point". The scores are the team's judgement — the arithmetic only makes that judgement visible and arguable.

🤔 Why

Because the most expensive decisions (lesson 01) are also the ones whose reasons are forgotten fastest. Without the why, teams either never touch a decision (fear) or undo it without knowing what it protected (churn). A weighted table forces the team to say what it values before it picks, and the weight check says when the decision should be reopened — which turns "we might need microservices one day" into a concrete trigger.

🔧 How (in this repo)

SCENARIOS in arch/models.py holds five scenarios with weights 1–3; OPTIONS holds each option's scores 1–5 in the same order. atam(options, scenarios, weights) sums weight × score. flip_weight(attr, rival) raises one attribute's weight from 1 upward and returns the first weight at which rival scores highest (or None). adr(number, title, context, decision, consequences) returns a Nygard-style ADR as Markdown.

🧪 Try it

python3 arch/demo.py adr
python3 - <<'EOF'
import sys; sys.path.insert(0, "arch"); from models import atam, SCENARIOS, adr
base = [s[2] for s in SCENARIOS]
for w in (1, 2, 3, 4, 5):
    t = atam(weights=base[:3] + [w] + base[4:])
    print(f"deployability weight {w}: " + " · ".join(f"{o} {v}" for o, v in t.items()) + f" → {max(t, key=t.get)}")
print(adr(7, "A modular monolith for the school app", "4 departments, a team of 3, results-day peaks.",
          "One deployable, departments as modules, boundaries checked in CI.", ["one transaction per request", "no independent deploys yet"]))
EOF

✅ Verify — what you should see

adr prints:

   modular monolith [4, 5, 5, 2, 3] → 42
   monolith         [2, 5, 5, 1, 3] → 35
   microservices    [4, 2, 3, 5, 5] → 34
   weights matter: microservices would win if deployability weighed 4 (not 1), or scalability 6 (not 1)

Your snippet prints:

deployability weight 1: monolith 35 · modular monolith 42 · microservices 34 → modular monolith
deployability weight 2: monolith 36 · modular monolith 44 · microservices 39 → modular monolith
deployability weight 3: monolith 37 · modular monolith 46 · microservices 44 → modular monolith
deployability weight 4: monolith 38 · modular monolith 48 · microservices 49 → microservices
deployability weight 5: monolith 39 · modular monolith 50 · microservices 54 → microservices
# ADR-0007: A modular monolith for the school app

Status: Accepted

## Context
4 departments, a team of 3, results-day peaks.

## Decision
One deployable, departments as modules, boundaries checked in CI.

## Consequences
- one transaction per request
- no independent deploys yet

🏁 What you just proved

With today's weights the modular monolith wins clearly (42 vs 35 vs 34). But the answer is not fixed: if releasing one department without the others became worth 4 instead of 1, microservices would win by a single point (49 vs 48). That tells you two things. First, the decision is reasonably robust — deployability must become more important than modifiability before it flips. Second, it tells you what to watch: the ADR's consequences say "revisit if deployability weight reaches 4", so a future team knows the trigger instead of re-arguing taste. The monolith never wins at any of these weights — the walls between departments (modifiability 4 vs 2) are worth having.

⚠️ Common mistakes

ADRs written after the fact to justify a decision already made
an ADR per trivial choice — then nobody reads any of them
editing an accepted ADR instead of superseding it — the history is lost
scores and weights chosen by one person, or after the answer is known
trusting the total to two decimal places — the scores are judgements; look at the gaps and the flip points
no "revisit when" — the decision can never be safely reopened

🏭 In production

On a real project — Nat Pryce's adr-tools keeps ADRs as numbered Markdown files:

adr init docs/architecture/decisions          # creates 0001-record-architecture-decisions.md
adr new A modular monolith for the school app # 0002-a-modular-monolith-for-the-school-app.md
adr new -s 2 Split grades into its own service   # a new ADR that supersedes 0002
adr list

A Nygard-style ADR, as a file in the repo:

# 7. A modular monolith for the school app

Date: 2026-09-01

## Status
Accepted

## Context
Four departments (admissions, grades, fees, timetable), a team of three, a 20× spike on
results day. Scored: modular monolith 42, monolith 35, microservices 34.

## Decision
One deployable. Departments are top-level packages. import-linter contracts keep them apart.

## Consequences
- One database transaction per request; no sagas.
- No independent deploys: a fees change redeploys grades.
- Revisit if independent deployability becomes as important as modifiability.

Other popular templates are MADR (Markdown Any Decision Records), which adds "considered options" with pros and cons, and Y-statements ("In the context of …, facing …, we decided … to achieve …, accepting …").

🏭 Why this matters in production: find the decision your team re-argues most often. Write its ADR this week, including the trigger for revisiting it — and link it from the code it governs.

⏭️ Next

Decisions made, rules checked, drawings true. But a school grows every term. How do you change a building while children are inside? Evolving architecture — and the whole picture.

git checkout lesson-12-evolution

← Previousc4 Next →evolution

This page is the lesson's README from the lesson-11-adrs branch, shown here so the whole School stays on one site. Code files open on GitHub at the same branch.