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

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

🏛️ धडा 01 — Architecture म्हणजे काय: बदलायला महाग असलेले निर्णय

📍 तुम्ही इथे आहात: 12 पैकी धडा 01 · पुढे: lesson-02-modularity

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

संपूर्ण कोर्स ज्या एका कल्पनेवर उभा आहे: architecture म्हणजे नंतर बदलायला महाग असलेल्या निर्णयांचा संच — आणि ते निर्णय जे गुण (the "-ilities") मिळवून देतात किंवा ज्यांची किंमत घेतात. हा कोर्स एक खरा, छोटा codebase पाहतो: काही terms मध्ये वाढलेले शाळेचे एक app. आपण तो शाळेच्या इमारतीचा नकाशा म्हणून वाचतो: modules म्हणजे खोल्या, imports म्हणजे खोल्यांमधील मार्गिका आणि दारे, आणि layers म्हणजे मजले. पूर्ण कोर्सभर तुम्ही वापराल अशा खऱ्या files:

arch/sample/schoolapp/ — इमारत: शाळेच्या app चे 13 छोटे Python modules, ज्यात काही समस्या मुद्दाम पेरलेल्या आहेत
arch/analyze.py — निरीक्षक: Python च्या ast module ने code वाचतो आणि coupling, cycles, layer आणि ring नियम, विभाग, fitness functions आणि C4 model मोजतो
arch/models.py — scanner ला जे दिसू शकत नाही त्यासाठी छोटे शिकवणी models: शैली आणि त्यांची किंमत, events आणि CQRS, data ownership, trade-off गुणांकन, strangler fig
arch/demo.py — प्रत्येक धडा एक छोटा program म्हणून (python3 arch/demo.py <section>; sections: decisions modularity layers hexagonal ddd styles events data fitness c4 adr evolve)
arch/test_arch.py — इमारतीच्या नियमांवरचे 12 checks
demo-output.txt — निरोगी run काय छापतो

🎒 सुरू करण्याआधी: तुम्हाला फक्त Python 3 लागेल, बाकी काहीही नाही — pip install नाही, cloud account नाही. Analyzer sample च्या source files फक्त वाचतो; तो त्या कधीच चालवत नाही. सगळे sorted आहे, म्हणून प्रत्येक run तेच आकडे छापतो. जिथे lab सोपे करतो (network hop ची किंमत, trade-off table मधील गुण), तिथे धडा teaching model असे सांगतो. on a real project अशी खूण असलेले commands खरी tools (import-linter, ArchUnit, Structurizr) वापरतात, जी तुम्ही स्वतः install करता.

🧭 हे कुठे बसते: System Design शाळा distributed systems डिझाइन करते (caches, queues, sharding, पूर्ण केलेली designs). ही शाळा codebase च्या आतल्या आणि codebases च्या मधल्या रचनेबद्दल आहे: खोल्या, मार्गिका, मजले आणि विभाग.

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

कतरिना शाळेच्या नव्या इमारतीचे नियोजन करते आहे. 🏫 काही निर्णय नंतर सहज बदलता येतात: वर्गाच्या भिंतींचा रंग, posters कुठे लावायचे. एक weekend आणि रंगाचा ब्रश, झाले.

इतर निर्णय नंतर बदलणे खूप अवघड असते: जिना कुठे असेल, कोणत्या भिंती छत तोलून धरतात, किती मजले आहेत. इमारत मुलांनी भरली की जिना हलवणे म्हणजे अर्धी शाळा महिनोनमहिने बंद ठेवणे.

Architecture म्हणजे हा दुसऱ्या प्रकारचा निर्णय. तो जिना आहे, रंग नव्हे.

आणि परिपूर्ण इमारत अशी कोणतीच नसते. अनेक दारे असलेल्या इमारतीत फिरणे सोपे, पण ती सुरक्षित ठेवणे अवघड. जाड भिंतींची इमारत शांत असते, पण महाग पडते. कतरिनाला या शाळेसाठी सगळ्यात महत्त्वाचे थोडेच गुण निवडावे लागतात — आणि त्यांची किंमत स्वीकारावी लागते.

🗺️ आकृती

flowchart LR
    subgraph cheap["🎨 cheap to change (design)"]
      v["rename a variable<br/>touches 1 room"]
      p["repaint a room<br/>(a private function)"]
    end
    subgraph costly["🏗️ expensive to change (architecture)"]
      port["change domain.ports<br/>ripples into 8 of 12 rooms"]
      adm["change domain.admissions<br/>ripples into 8 of 12 rooms"]
    end
    ilities["⚖️ the -ilities Katrina picks:<br/>modifiability · testability · availability"]
    costly --> ilities

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

❓ काय

Software architecture — system ची महत्त्वाची रचना: त्याचे भाग, ते एकमेकांवर कसे अवलंबून आहेत, आणि त्यामागची कारणे. Grady Booch यांनी असे मांडले: architecture म्हणजे महत्त्वाच्या design निर्णयांचा संच, जिथे महत्त्व बदलाच्या किमतीने मोजले जाते.
Module (एक खोली) — नाव असलेले code चे एक एकक: इथे एक Python file, जसे domain/grades.py. Analyzer तिला domain.grades म्हणतो.
Dependency (एक मार्गिका) — खोली A खोली B ला import करते. B बदलली, तर A लाही बदलावे लागू शकते. Lab मध्ये analyze.scan() Python च्या ast module ने प्रत्येक import आणि from … import वाचतो.
Blast radius — मार्गिकांमधून, थेट किंवा इतरांमार्फत, एखाद्या खोलीपर्यंत पोहोचणारी प्रत्येक खोली. तिथला बदल त्या सगळ्यांपर्यंत पोहोचू शकतो. Lab याला dependents(g, m) म्हणतो.
Architecture characteristics (the "-ilities") — system मध्ये असायला हवे असे गुण जे features नाहीत: modifiability, testability, availability, performance, scalability, security, deployability, आणि इतर. ISO/IEC 25010 हे standard performance efficiency, reliability, security, maintainability आणि portability असे quality characteristics सूचीबद्ध करते.
Driving characteristics — हा system यशस्वी होतो की नाही हे ठरवणारे थोडेच -ilities. प्रत्येकाला फक्त एक शब्द नव्हे, तर test करता येईल असा scenario लागतो ("marks चे नियम database शिवाय test मध्ये चालतात").
Trade-off — प्रत्येक characteristic ची काही किंमत असते, बहुतेकदा दुसरे characteristic. जास्त वेगळे भाग → स्वतंत्र बदल सोपा, पण चालवायला जास्त हलणारे भाग. म्हणूनच architecture मध्ये "it depends" हे पहिले प्रामाणिक उत्तर असते — आणि त्यानंतर कशावर.

🤔 का

कारण स्वस्त निर्णय आपोआप सुधारतात आणि महाग निर्णय सुधारत नाहीत. वाईट नाव दिलेल्या variable ची किंमत एक मिनिट. सगळे जण import करतात आणि ज्यात database मिसळलेला आहे असे core module, नियम बदलले की दर वेळी आठवडे खाते — आणि त्यावर टेकणाऱ्या प्रत्येक नव्या खोलीसोबत ती किंमत वाढते. कोणते निर्णय महाग आहेत हे माहीत असले की विचाराचा वेळ कुठे घालवायचा ते कळते. Driving -ilities ना नाव दिले की तुम्ही कशासाठी optimise करत आहात ते कळते, आणि दोन चांगले engineers आवडीनिवडीवर वाद घालणे थांबवून trade-offs ची तुलना करू लागतात.

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

arch/analyze.py मधील scan() arch/sample/schoolapp/ मधून फिरतो, प्रत्येक module parse करतो (रिकाम्या __init__.py files सोडून) आणि त्याचे imports एका graph म्हणून नोंदवतो: {room: [rooms it imports]}. dependents(g, m) मार्गिकांवरून उलट चालत m पर्यंत पोहोचणारी प्रत्येक खोली शोधतो; reach(g, m) त्यांवरून पुढे चालतो. arch/demo.py मधील decisions() सगळ्यात मोठे आणि सगळ्यात छोटे blast radii आणि arch/models.py मधील DRIVING मधून कतरिनाचे तीन driving characteristics छापतो.

🧪 करून पाहा

python3 arch/demo.py decisions
python3 - <<'EOF'
import sys; sys.path.insert(0, "arch"); from analyze import scan, dependents, reach
g = scan().imports
for m in sorted(g, key=lambda m: (-len(dependents(g, m)), m)):
    print(f"{m:<18} used by {len(dependents(g, m)):>2} rooms · uses {len(reach(g, m)):>2} rooms")
EOF
python3 arch/test_arch.py

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

decisions हे छापतो:

── the building: arch/sample/schoolapp has 13 rooms (modules) and 24 corridors (imports), 187 lines
   blast radius = the rooms a change can ripple into (every room that reaches it through corridors):
   domain.admissions   8 of 12 rooms
   domain.ports        8 of 12 rooms
   domain.grades       4 of 12 rooms
   domain.timetable    0 of 12 rooms
   main                0 of 12 rooms

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

domain.admissions  used by  8 rooms · uses  0 rooms
domain.ports       used by  8 rooms · uses  0 rooms
domain.grades      used by  4 rooms · uses  3 rooms
infra.db           used by  4 rooms · uses  3 rooms
domain.fees        used by  3 rooms · uses  1 rooms
infra.email        used by  3 rooms · uses  1 rooms
web.format         used by  3 rooms · uses  0 rooms
app.enrol          used by  2 rooms · uses  3 rooms
app.fees_service   used by  2 rooms · uses  3 rooms
app.report_card    used by  2 rooms · uses  4 rooms
web.views          used by  1 rooms · uses 10 rooms
domain.timetable   used by  0 rooms · uses  1 rooms
main               used by  0 rooms · uses 11 rooms

Tests शेवटी 12/12 passed छापतात.

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

एकाच छोट्या codebase मध्ये स्वस्त खोल्या आणि महाग खोल्या असतात. domain.timetable बदलली तर इतर कोणालाही धक्का लागत नाही (0 dependents). domain.ports किंवा domain.admissions चा आकार बदलला तर तो बदल इतर 12 पैकी 8 खोल्यांपर्यंत पोहोचू शकतो. हा फरक म्हणजेच architecture. आणि web.format पाहा: एक छोटा presentation helper, ज्याचे 3 dependents आहेत — त्यातली एक domain.timetable, एक core खोली जी वरच्या मजल्यापर्यंत वर पोहोचली. धडे 03 आणि 04 ही मार्गिका पकडतात.

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

architecture म्हणजे boxes-and-arrows चे चित्र असे समजणे — ते चित्र जे निर्णय (कदाचित) दाखवते, ते म्हणजे architecture
प्रत्येक -ility "महत्त्वाचे" म्हणून लिहिणे — मग त्यातले कोणतेच निर्णयाला दिशा देत नाही
scenario नसलेले -ilities ("ते scalable असायला हवे") — ते कोणीच test किंवा trade करू शकत नाही
प्रत्येक निर्णयाला architecture मानणे, म्हणजे प्रत्येक गोष्टीसाठी meeting
महाग निर्णय चुकून लवकर घेऊन टाकणे (सगळे import करतात असे एक सामायिक module)

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

On a real project — git history मधून सगळ्यात जास्त बदलणाऱ्या खोल्या (hot spots) शोधा; मोठा blast radius असलेला hot spot म्हणजे जिथे architecture चे काम सगळ्यात आधी फळ देते:

git log --since="1 year ago" --format= --name-only -- '*.py' | sort | uniq -c | sort -rn | head -10

एक import प्रत्यक्षात काय load करतो, आणि प्रत्येक import ला किती वेळ लागतो, हे Python दाखवू शकतो:

python3 -X importtime -c "import yourapp.domain.grades" 2>&1 | tail -15

Driving characteristics code च्या शेजारी scenarios म्हणून लिहून ठेवा, उदाहरणार्थ docs/architecture/characteristics.md मध्ये:

testability   — the marks rules run in a unit test with no database, in under 1 s
modifiability — a new department ships within one term without editing the others
availability  — report cards open on results day (99.9% of requests succeed)

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: तुमच्या पुढच्या design meeting आधी तीन driving characteristics आणि प्रत्येकी एक scenario लिहा. मग समोरच्या प्रत्येक पर्यायासाठी विचारा: तो कोणत्या characteristic ला मदत करतो आणि कोणत्याची किंमत घेतो.

⏭️ पुढे

Blast radius मार्गिकांनी बनलेला असतो. एका खोलीला किती मार्गिका असाव्यात — आणि कोणत्या? Coupling आणि cohesion, मोजून.

git checkout lesson-02-modularity

🏛️ Lesson 01 — What architecture is: the decisions that are expensive to change

📍 You are here: Lesson 01 of 12 · Next: lesson-02-modularity

📦 What's in this branch

The one idea this whole course hangs on: architecture is the set of decisions that are expensive to change later — and the qualities (the "-ilities") those decisions buy or cost. The course looks at a real, tiny codebase: a school app that grew for a few terms. We read it as the school building's floor plan: modules are rooms, imports are corridors and doors between rooms, and layers are floors. Real files you will use all the way through:

arch/sample/schoolapp/ — the building: 13 small Python modules of a school app, with a few problems planted on purpose
arch/analyze.py — the inspector: reads the code with Python's ast module and measures coupling, cycles, layer and ring rules, departments, fitness functions and a C4 model
arch/models.py — small teaching models for what a scanner cannot see: styles and their costs, events and CQRS, data ownership, trade-off scoring, the strangler fig
arch/demo.py — every lesson as a small program (python3 arch/demo.py <section>; sections: decisions modularity layers hexagonal ddd styles events data fitness c4 adr evolve)
arch/test_arch.py — 12 checks on the building's rules
demo-output.txt — what a healthy run prints

🎒 Before you start: you need Python 3 and nothing else — no pip install, no cloud account. The analyzer only reads the sample's source files; it never runs them. Everything is sorted, so every run prints the same numbers. Where the lab simplifies (the cost of a network hop, the scores in a trade-off table), the lesson says teaching model. Commands marked on a real project use real tools (import-linter, ArchUnit, Structurizr) that you install yourself.

🧭 Where this sits: the System Design school designs distributed systems (caches, queues, sharding, worked designs). This school is about the structure inside a codebase and between codebases: rooms, corridors, floors and departments.

🧒 Explain like I'm 5

Katrina is planning a new school building. 🏫 Some choices are easy to change later: the colour of the classroom walls, where the posters go. A weekend with a paint brush, done.

Other choices are very hard to change later: where the staircase goes, which walls hold up the roof, how many floors there are. Once the building is full of children, moving the staircase means closing half the school for months.

Architecture is the second kind of choice. It is the staircase, not the paint.

And there is no perfect building. A building with many doors is easy to walk through but hard to keep safe. A building with thick walls is quiet but costs more. Katrina has to pick the few qualities that matter most for this school — and accept what they cost.

🗺️ Diagram

flowchart LR
    subgraph cheap["🎨 cheap to change (design)"]
      v["rename a variable<br/>touches 1 room"]
      p["repaint a room<br/>(a private function)"]
    end
    subgraph costly["🏗️ expensive to change (architecture)"]
      port["change domain.ports<br/>ripples into 8 of 12 rooms"]
      adm["change domain.admissions<br/>ripples into 8 of 12 rooms"]
    end
    ilities["⚖️ the -ilities Katrina picks:<br/>modifiability · testability · availability"]
    costly --> ilities

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

❓ What

Software architecture — the important structure of a system: its parts, how they depend on each other, and the reasons. Grady Booch put it this way: architecture is the set of significant design decisions, where significant is measured by cost of change.
Module (a room) — one unit of code with a name: here, one Python file such as domain/grades.py. The analyzer calls it domain.grades.
Dependency (a corridor) — room A imports room B. If B changes, A may have to change too. In the lab, analyze.scan() reads every import and from … import with Python's ast module.
Blast radius — every room that can reach a room through corridors, directly or through others. A change there can ripple into all of them. The lab calls it dependents(g, m).
Architecture characteristics (the "-ilities") — qualities the system must have that are not features: modifiability, testability, availability, performance, scalability, security, deployability, and more. The standard ISO/IEC 25010 lists quality characteristics such as performance efficiency, reliability, security, maintainability and portability.
Driving characteristics — the few -ilities that decide whether this system succeeds. Each one needs a scenario you can test ("the marks rules run in a test without a database"), not just a word.
Trade-off — every characteristic costs something, often another characteristic. More separate parts → easier independent change, but more moving parts to run. This is why "it depends" is the honest first answer in architecture — followed by on what.

🤔 Why

Because the cheap decisions fix themselves and the expensive ones do not. A badly named variable costs a minute. A core module that everything imports, with the database mixed in, costs weeks every time the rules change — and the cost grows with every new room that leans on it. Knowing which decisions are expensive tells you where to spend your thinking time. Naming the driving -ilities tells you what you are optimising for, so two good engineers stop arguing about taste and start comparing trade-offs.

🔧 How (in this repo)

scan() in arch/analyze.py walks arch/sample/schoolapp/, parses each module (not the empty __init__.py files) and records its imports as a graph: {room: [rooms it imports]}. dependents(g, m) walks the corridors backwards to find every room that reaches m; reach(g, m) walks them forwards. decisions() in arch/demo.py prints the biggest and smallest blast radii and Katrina's three driving characteristics from DRIVING in arch/models.py.

🧪 Try it

python3 arch/demo.py decisions
python3 - <<'EOF'
import sys; sys.path.insert(0, "arch"); from analyze import scan, dependents, reach
g = scan().imports
for m in sorted(g, key=lambda m: (-len(dependents(g, m)), m)):
    print(f"{m:<18} used by {len(dependents(g, m)):>2} rooms · uses {len(reach(g, m)):>2} rooms")
EOF
python3 arch/test_arch.py

✅ Verify — what you should see

decisions prints:

── the building: arch/sample/schoolapp has 13 rooms (modules) and 24 corridors (imports), 187 lines
   blast radius = the rooms a change can ripple into (every room that reaches it through corridors):
   domain.admissions   8 of 12 rooms
   domain.ports        8 of 12 rooms
   domain.grades       4 of 12 rooms
   domain.timetable    0 of 12 rooms
   main                0 of 12 rooms

Your snippet prints:

domain.admissions  used by  8 rooms · uses  0 rooms
domain.ports       used by  8 rooms · uses  0 rooms
domain.grades      used by  4 rooms · uses  3 rooms
infra.db           used by  4 rooms · uses  3 rooms
domain.fees        used by  3 rooms · uses  1 rooms
infra.email        used by  3 rooms · uses  1 rooms
web.format         used by  3 rooms · uses  0 rooms
app.enrol          used by  2 rooms · uses  3 rooms
app.fees_service   used by  2 rooms · uses  3 rooms
app.report_card    used by  2 rooms · uses  4 rooms
web.views          used by  1 rooms · uses 10 rooms
domain.timetable   used by  0 rooms · uses  1 rooms
main               used by  0 rooms · uses 11 rooms

The tests end with 12/12 passed.

🏁 What you just proved

The same small codebase has cheap rooms and expensive rooms. Changing domain.timetable touches nobody else (0 dependents). Changing the shape of domain.ports or domain.admissions can ripple into 8 of the other 12 rooms. That difference is the architecture. And look at web.format: a tiny presentation helper with 3 dependents — one of them is domain.timetable, a core room that reached up to the top floor. Lessons 03 and 04 catch that corridor.

⚠️ Common mistakes

thinking architecture is the boxes-and-arrows drawing — it is the decisions the drawing (maybe) shows
listing every -ility as "important" — then none of them guides a choice
-ilities with no scenario ("it must be scalable") — nobody can test or trade them
treating every decision as architecture, so everything takes a meeting
making the expensive decisions early by accident (a shared module everyone imports)

🏭 In production

On a real project — find the rooms that change most often (the hot spots) from git history; a hot spot with a big blast radius is where architecture work pays back first:

git log --since="1 year ago" --format= --name-only -- '*.py' | sort | uniq -c | sort -rn | head -10

Python can show what one import really loads, and how long each import takes:

python3 -X importtime -c "import yourapp.domain.grades" 2>&1 | tail -15

Write the driving characteristics down as scenarios next to the code, for example in docs/architecture/characteristics.md:

testability   — the marks rules run in a unit test with no database, in under 1 s
modifiability — a new department ships within one term without editing the others
availability  — report cards open on results day (99.9% of requests succeed)

🏭 Why this matters in production: before your next design meeting, write the three driving characteristics and one scenario each. Then, for every option on the table, ask which characteristic it helps and which it costs.

⏭️ Next

A blast radius is made of corridors. How many corridors should a room have — and which ones? Coupling and cohesion, measured.

git checkout lesson-02-modularity

← Course homeall lessons Next →modularity

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