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

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

🔍 धडा 09 — Fitness functions: कधीही सुट्टी न घेणारी इमारत-निरीक्षक

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

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

धडे 01–08, आणि अंमलबजावणी. आधीच्या धड्यांमधला प्रत्येक नियम आता प्रत्येक push वर चालणारी architecture test बनतो — एक fitness function. नवीन मार्गिका आराखडा मोडते तेव्हा build fail होतो, जसा unit test मोडल्यावर होतो. fitness() आणि check command arch/analyze.py मध्ये, आणि fitness arch/demo.py मध्ये.

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

कतरिनाने एक सुंदर इमारतीचा नकाशा काढला. मग बांधकाम करणारे आले. 👷‍♀️ त्यांच्यापैकी एक घाईत होता आणि बंद राहायला हवी होती अशा भिंतीतून त्याने दार फोडले. कोणाच्याच लक्षात आले नाही. सहा महिन्यांनी अशी दहा दारे झाली, आणि भिंतीवरच्या नकाशाचा इमारतीशी काहीच संबंध उरला नाही.

म्हणून ऐश्वर्या इमारत-निरीक्षक बनते. 📋 तिच्याकडे एक यादी आहे: "नियमपुस्तिकेच्या खोलीतून भांडार खोलीकडे दार नाही", "दोन्ही दिशांना जाणारे जिने नाहीत", "विभाग फक्त आपापल्या खिडक्यांमधूनच बोलतात". आणि सगळ्यात छान गोष्ट: ती दररोज, आपोआप तपासते, कोणतेही नवीन दार टिकू देण्याआधी.

नवीन shortcut? ऐश्वर्याची यादी लाल होते, आणि कोणी ते दुरुस्त करेपर्यंत — किंवा हेतुपूर्वक आराखडा बदलेपर्यंत — ते दार स्वीकारले जात नाही.

🗺️ आकृती

flowchart LR
    push["👩‍💻 git push"] --> ci["⚙️ CI"]
    ci --> unit["🧪 unit tests"]
    ci --> fit["🔍 fitness functions<br/>python3 arch/analyze.py check"]
    fit --> r1["❌ no import cycles"]
    fit --> r2["❌ dependencies point inward"]
    fit --> r3["❌ domain imports only the domain"]
    fit --> r4["❌ departments apart"]
    fit --> r5["✅ fan-out ≤ 5"]
    fit --> r6["✅ domain instability ≤ 0.5"]
    r1 --> fail["exit code 1: the merge is blocked"]

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

❓ काय

Fitness function — system architecture च्या उद्दिष्टाच्या किती जवळ आहे हे सांगणारी कोणतीही वस्तुनिष्ठ, आपोआप चालणारी तपासणी. हा शब्द Building Evolutionary Architectures (Neal Ford, Rebecca Parsons, Patrick Kua; 2017, दुसरी आवृत्ती 2022 मध्ये Pramod Sadalage यांच्यासह) मधून आला आहे, आणि तो evolutionary computing मधून घेतलेला आहे.
Architecture test — रचनेबद्दलची fitness function: import नियम, layers, cycles, नावे. ती unit test सारखी चालते आणि build fail करते.
Atomic विरुद्ध holistic — atomic तपासणी एकच गोष्ट पाहते (cycles नाहीत); holistic अनेक गोष्टी एकत्र करते (latency आणि error rate एकत्र तपासणारी load test).
Triggered विरुद्ध continual — triggered एखाद्या घटनेवर चालते (प्रत्येक push); continual production मध्ये सतत चालते (p99 latency वरचा monitor). या धड्यातील तपासण्या triggered आहेत.
Threshold — metric ज्याच्या खाली राहायलाच हवा अशी मर्यादा: fan-out ≤ 5, domain instability ≤ 0.5. आजच्या आकड्यांवरून त्या निवडा आणि कालांतराने घट्ट करा (एक "ratchet").
Exception list — माहीत असलेली उल्लंघने हेतुपूर्वक लिहून ठेवलेली (import-linter चे ignore_imports), म्हणजे तपासणी आज हिरवी होऊ शकते आणि तरीही नवीन उल्लंघने थांबवते.

🤔 का

कारण architecture एका वेळी एक, योग्य वाटणाऱ्या import ने झिजते, आणि code review ला 3 ओळींच्या diff मध्ये रचनेचा नियम दिसू शकत नाही. कोणीच न तपासणारा आराखडा म्हणजे फक्त इच्छा. Build fail करणारा आराखडा म्हणजे टिकून राहणारा निर्णय — आणि नियमच चुकीचा असेल, तर तो बदलणे हा शांतपणे होणारा drift न राहता दिसणारा, review झालेला बदल ठरतो.

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

arch/analyze.py मधले fitness(g, classes, max_fan_out=5, max_core_instability=0.5) सहा नियम चालवते, प्रत्येक आधीच्या धड्यातून बनलेला: cycles() (धडा 02/12), ring_violations() आणि core_leaks() (धडा 04), context_edges() (धडा 05), प्रत्येक खोलीचा सर्वात मोठा fan-out (धडा 02), आणि domain ची instability I (धडा 02). प्रत्येक नियम (name, passed, detail) परत करतो. python3 arch/analyze.py check ते छापते आणि कोणताही fail झाला तर exit 1 करते — CI step ला नेमके हेच हवे असते.

🧪 करून पाहा

python3 arch/demo.py fitness
python3 arch/analyze.py check; echo "exit code $?"
python3 - <<'EOF'
import sys; sys.path.insert(0, "arch"); from analyze import scan, apply, fitness, FIXES
cb = scan(); fixed = apply(cb.imports, remove=FIXES)
oops = apply(fixed, add=[("domain.fees", "infra.db")])     # a new shortcut, pushed on a Friday
for name, ok, detail in fitness(oops, cb.classes):
    print(f"{'PASS' if ok else 'FAIL'}  {name:<40} {detail}")
EOF

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

fitness हे छापते:

── the fitness functions run on every push (python3 arch/analyze.py check)
   FAIL  no import cycles                         1 cycle(s): domain.grades ↔ infra.db
   FAIL  dependencies point inward                3 outward import(s)
   FAIL  the domain imports only the domain       2 leak(s)
   FAIL  departments do not import each other     2 cross-context import(s)
   PASS  fan-out ≤ 5 per room (main excluded)     max 4 (web.views)
   PASS  domain instability ≤ 0.5                 I = 0.29
   after removing the 5 planted corridors: 6/6 pass · CI exit code 0

check command चा शेवट असा होतो:

4 rule(s) failed
exit code 1

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

PASS  no import cycles                         0 cycle(s)
FAIL  dependencies point inward                1 outward import(s)
FAIL  the domain imports only the domain       1 leak(s)
FAIL  departments do not import each other     1 cross-context import(s)
PASS  fan-out ≤ 5 per room (main excluded)     max 4 (web.views)
PASS  domain instability ≤ 0.5                 I = 0.17

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

दिलेली इमारत 6 पैकी 4 नियमांत fail होते आणि तपासणी exit 1 करते — CI job merge थांबवेल. पेरलेल्या 5 मार्गिका काढल्यावर सर्व 6 pass होतात आणि ती exit 0 करते. मग शुक्रवारचा एक shortcut — domain.fees ने infra.db import करणे — तीन नियमांनी एकाच वेळी पकडला जातो: तो बाहेरच्या दिशेने जातो, तो domain गळू देतो, आणि तो fees विभागातून grades च्या मालकीच्या खोलीत जातो. कशाने तो पकडला नाही ते पाहा: domain ची instability फक्त 0.00 वरून 0.17 झाली, अजूनही 0.5 threshold च्या खाली. Metric thresholds ढोबळ असतात; स्पष्ट नियम धारदार असतात. दोन्ही वापरा.

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

जुन्या codebase ला exception list शिवाय कडक नियम लावणे → तपासणी कायमची लाल राहते आणि बंद केली जाते
फक्त wiki page वर लिहिलेले नियम
कोणीच कधी घट्ट न करणारे thresholds
नियम फक्त happy path वर test करणे — पेरलेल्या उल्लंघनावर तो fail होतो याची खात्री करा (snippet करतो तसे)
pull-request check मध्ये न ठेवता, कोणीच न पाहणाऱ्या वेगळ्या nightly job मध्ये architecture checks

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

खऱ्या project वर — checks unit tests च्याच pipeline मध्ये चालवा. GitHub Actions:

name: architecture
on: [push, pull_request]
jobs:
  fitness:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python3 arch/analyze.py check
      - run: pip install import-linter && lint-imports

इतर भाषांमध्ये हीच कल्पना:

Java: ArchUnit — noClasses().that().resideInAPackage("..domain..").should().dependOnClassesThat().resideInAPackage("..infra.."), आणि slices().matching("..school.(*)..").should().beFreeOfCycles()
JavaScript / TypeScript: dependency-cruiser — no-circular नियमासह npx depcruise src --config .dependency-cruiser.js
.NET: NetArchTest — Types.InAssembly(asm).That().ResideInNamespace("School.Domain").ShouldNot().HaveDependencyOn("School.Infra").GetResult()

Exception list मुळे तुम्ही नियम आजच चालू करू शकता (import-linter):

[importlinter:contract:core]
name = The domain imports no adapters
type = forbidden
source_modules = schoolapp.domain
forbidden_modules = schoolapp.infra
# a known violation, ticket SCH-142 — the list may shrink, never grow
ignore_imports =
    schoolapp.domain.grades -> schoolapp.infra.db

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: तुमचे रचनेचे दोन सर्वात महत्त्वाचे नियम निवडा, या आठवड्यात ते tests म्हणून लिहा, आणि एक उल्लंघन पेरून ते fail होताना पाहा. जो नियम तुम्ही कधी fail होताना पाहिलेला नाही, तो चालतो की नाही हे तुम्हाला माहीत नसते.

⏭️ पुढे

निरीक्षक इमारत तपासते. आता ती काढा — code मधूनच, म्हणजे चित्र खोटे बोलू शकत नाही. C4 model.

git checkout lesson-10-c4

🔍 Lesson 09 — Fitness functions: the building inspector who never takes a day off

📍 You are here: Lesson 09 of 12 · Previous: lesson-08-data-ownership · Next: lesson-10-c4

📦 What's in this branch

Lessons 01–08, plus enforcement. Every rule from the earlier lessons becomes an architecture test that runs on every push — a fitness function. The build fails when a new corridor breaks the plan, the same way it fails when a unit test breaks. fitness() and the check command in arch/analyze.py, and fitness in arch/demo.py.

🧒 Explain like I'm 5

Katrina drew a beautiful floor plan. Then the builders came. 👷‍♀️ One of them was in a hurry and knocked a door through a wall that was supposed to stay closed. Nobody noticed. Six months later, there were ten such doors, and the plan on the wall had nothing to do with the building.

So Aishwarya becomes the building inspector. 📋 She has a checklist: "no door from the rule book to the store room", "no stairs going both ways", "departments only talk through their windows". And the best part: she checks every single day, automatically, before any new door is allowed to stay.

A new shortcut? Aishwarya's list goes red, and the door is not accepted until someone fixes it — or changes the plan on purpose.

🗺️ Diagram

flowchart LR
    push["👩‍💻 git push"] --> ci["⚙️ CI"]
    ci --> unit["🧪 unit tests"]
    ci --> fit["🔍 fitness functions<br/>python3 arch/analyze.py check"]
    fit --> r1["❌ no import cycles"]
    fit --> r2["❌ dependencies point inward"]
    fit --> r3["❌ domain imports only the domain"]
    fit --> r4["❌ departments apart"]
    fit --> r5["✅ fan-out ≤ 5"]
    fit --> r6["✅ domain instability ≤ 0.5"]
    r1 --> fail["exit code 1: the merge is blocked"]

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

❓ What

Fitness function — any objective, automatic check that tells you how close the system is to an architectural goal. The term comes from Building Evolutionary Architectures (Neal Ford, Rebecca Parsons, Patrick Kua; 2017, second edition 2022 with Pramod Sadalage), borrowed from evolutionary computing.
Architecture test — a fitness function about structure: import rules, layers, cycles, naming. It runs like a unit test and fails the build.
Atomic vs holistic — an atomic check looks at one thing (no cycles); a holistic one combines several (a load test that checks latency and error rate together).
Triggered vs continual — triggered runs on an event (every push); continual runs all the time in production (a monitor on p99 latency). This lesson's checks are triggered.
Threshold — a limit a metric must stay under: fan-out ≤ 5, domain instability ≤ 0.5. Pick them from today's numbers and tighten them over time (a "ratchet").
Exception list — known violations written down on purpose (import-linter's ignore_imports), so the check can go green today and still stop new ones.

🤔 Why

Because architecture decays one reasonable-looking import at a time, and code review cannot see a structural rule in a 3-line diff. A plan that nobody checks is a wish. A plan that fails the build is a decision that stays made — and when the rule is wrong, changing it is a visible, reviewed change instead of a quiet drift.

🔧 How (in this repo)

fitness(g, classes, max_fan_out=5, max_core_instability=0.5) in arch/analyze.py runs six rules, each built from an earlier lesson: cycles() (lesson 02/12), ring_violations() and core_leaks() (lesson 04), context_edges() (lesson 05), the largest fan-out per room (lesson 02), and the domain's instability I (lesson 02). Each rule returns (name, passed, detail). python3 arch/analyze.py check prints them and exits 1 if any failed — exactly what a CI step needs.

🧪 Try it

python3 arch/demo.py fitness
python3 arch/analyze.py check; echo "exit code $?"
python3 - <<'EOF'
import sys; sys.path.insert(0, "arch"); from analyze import scan, apply, fitness, FIXES
cb = scan(); fixed = apply(cb.imports, remove=FIXES)
oops = apply(fixed, add=[("domain.fees", "infra.db")])     # a new shortcut, pushed on a Friday
for name, ok, detail in fitness(oops, cb.classes):
    print(f"{'PASS' if ok else 'FAIL'}  {name:<40} {detail}")
EOF

✅ Verify — what you should see

fitness prints:

── the fitness functions run on every push (python3 arch/analyze.py check)
   FAIL  no import cycles                         1 cycle(s): domain.grades ↔ infra.db
   FAIL  dependencies point inward                3 outward import(s)
   FAIL  the domain imports only the domain       2 leak(s)
   FAIL  departments do not import each other     2 cross-context import(s)
   PASS  fan-out ≤ 5 per room (main excluded)     max 4 (web.views)
   PASS  domain instability ≤ 0.5                 I = 0.29
   after removing the 5 planted corridors: 6/6 pass · CI exit code 0

The check command ends with:

4 rule(s) failed
exit code 1

Your snippet prints:

PASS  no import cycles                         0 cycle(s)
FAIL  dependencies point inward                1 outward import(s)
FAIL  the domain imports only the domain       1 leak(s)
FAIL  departments do not import each other     1 cross-context import(s)
PASS  fan-out ≤ 5 per room (main excluded)     max 4 (web.views)
PASS  domain instability ≤ 0.5                 I = 0.17

🏁 What you just proved

The shipped building fails 4 of 6 rules and the check exits 1 — a CI job would block the merge. With the 5 planted corridors removed, all 6 pass and it exits 0. Then one Friday shortcut — domain.fees importing infra.db — is caught by three rules at once: it points outward, it leaks the domain, and it crosses from the fees department into a room owned by grades. Note what did not catch it: the domain's instability only moved from 0.00 to 0.17, still under the 0.5 threshold. Metric thresholds are coarse; explicit rules are sharp. Use both.

⚠️ Common mistakes

adding strict rules to an old codebase with no exception list → the check is red forever and gets switched off
rules that are only written on a wiki page
thresholds nobody ever tightens
testing the rule only on the happy path — make sure it fails on a planted violation (as the snippet does)
architecture checks in a separate nightly job nobody watches, instead of in the pull-request check

🏭 In production

On a real project — run the checks in the same pipeline as the unit tests. GitHub Actions:

name: architecture
on: [push, pull_request]
jobs:
  fitness:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python3 arch/analyze.py check
      - run: pip install import-linter && lint-imports

The same idea in other languages:

Java: ArchUnit — noClasses().that().resideInAPackage("..domain..").should().dependOnClassesThat().resideInAPackage("..infra.."), and slices().matching("..school.(*)..").should().beFreeOfCycles()
JavaScript / TypeScript: dependency-cruiser — npx depcruise src --config .dependency-cruiser.js with a no-circular rule
.NET: NetArchTest — Types.InAssembly(asm).That().ResideInNamespace("School.Domain").ShouldNot().HaveDependencyOn("School.Infra").GetResult()

An exception list lets you switch the rule on today (import-linter):

[importlinter:contract:core]
name = The domain imports no adapters
type = forbidden
source_modules = schoolapp.domain
forbidden_modules = schoolapp.infra
# a known violation, ticket SCH-142 — the list may shrink, never grow
ignore_imports =
    schoolapp.domain.grades -> schoolapp.infra.db

🏭 Why this matters in production: pick your two most important structural rules, write them as tests this week, and plant a violation to watch them fail. A rule you have never seen fail is a rule you do not know works.

⏭️ Next

The inspector checks the building. Now draw it — from the code, so the drawing cannot lie. The C4 model.

git checkout lesson-10-c4

← Previousdata ownership Next →c4

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