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

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

🏢 धडा 03 — Layers: मजले, आणि जिने कोणत्या दिशेने जातात

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

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

धडे 01–02, आणि एक नियम. पारंपरिक layered architecture code मजल्यांमध्ये रचते — सगळ्यात वर web (presentation), मग app (use cases), मग domain (business rules), आणि सगळ्यात खाली infra (database, email) — आणि एकच नियम: एखादा मजला फक्त त्याच्या खालचे मजले वापरू शकतो. Layer violations आपोआप कसे शोधायचे, strict विरुद्ध relaxed layering, आणि हा धडा एका आश्चर्याने का संपतो. arch/analyze.py मधील layer_violations() आणि arch/demo.py मधील layers().

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

शाळेच्या इमारतीला चार मजले आहेत. 🏢

सगळ्यात वरचा मजला — स्वागत कक्ष (web): पालक आत येतात आणि प्रश्न विचारतात.
दुसरा मजला — office (app): गोष्टी कशा करायच्या हे माहीत असलेला कर्मचारीवर्ग — मुलाचा प्रवेश करणे, report card छापणे.
तिसरा मजला — नियमपुस्तिका (domain): mark म्हणजे काय, सरासरी कशी काढायची.
तळमजला — भांडार आणि टपाल खोली (infra): कागदपत्रांची कपाटे आणि पत्रे.

नियम: तुम्ही जिन्याने खाली जाऊ शकता, वर कधीच नाही. Office नियमपुस्तिका पाहू शकते. नियमपुस्तिका दिवसाचे नाव कसे छापायचे हे विचारायला स्वागत कक्षाला फोन करू शकत नाही.

ऐश्वर्या clipboard घेऊन प्रत्येक मार्गिकेतून फिरते आणि जिन्याने वर जाणारी प्रत्येक मार्गिका लिहून ठेवते. ती यादी म्हणजे layer violations.

🗺️ आकृती

flowchart TB
    web["🖥️ web — reception (top floor)"]
    app["🧑‍🏫 app — the office"]
    domain["📚 domain — the rule book"]
    infra["🔌 infra — store room + post room (ground floor)"]
    web -->|"ok: down"| app
    app -->|"ok: down"| domain
    domain -->|"ok: down"| infra
    domain -.->|"❌ upward: timetable → web.format"| web
    infra -.->|"❌ upward ×3: db → grades, db → ports, email → ports"| domain
    app -.->|"strict only: skips a floor (enrol → email)"| infra

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

❓ काय

Layered architecture (n-tier) — code कामाच्या प्रकारानुसार आडव्या layers मध्ये विभागला जातो. Eric Evans यांचे Domain-Driven Design (2003) चार नावे देते: user interface, application, domain, infrastructure. अनेक web apps presentation, business, persistence, database वापरतात.
Layering चा नियम — एखादा layer फक्त त्याच्या खालच्या layers वर अवलंबून राहू शकतो. खालच्या कोणालाही वरचे काही अस्तित्वात आहे हे माहीत नसते. मग तळाला हात न लावता तुम्ही वरचा भाग (नवीन mobile screen) बदलू शकता.
Relaxed (open) layering — खालचा कोणताही layer चालतो; web मजला थेट domain कडे जाऊ शकतो.
Strict (closed) layering — फक्त लगेच खालचा layer. प्रत्येक request प्रत्येक मजल्यातून जाते. जास्त स्वच्छ, पण यातून architecture sinkhole anti-pattern (Mark Richards यांनी दिलेले नाव) तयार होऊ शकतो: काहीही न जोडता फक्त calls पुढे ढकलणारे layers.
Layer violation — नियम मोडणारा import: वर जाणारा (खालचा वरच्याला import करतो) किंवा, strict layering मध्ये, एखादा मजला वगळणारा.
Dependency rule — "source code dependencies फक्त आतल्या दिशेने, policies कडे जातात" याला Robert C. Martin यांनी (Clean Architecture) दिलेले नाव. पुढचा धडा दाखवतो की "आत" आणि "खाली" हे एकच नाहीत — आणि नेमके तेच या धड्याचे आश्चर्य आहे.

🤔 का

कारण दोन्ही दिशांनी जिने असलेल्या इमारतीच्या नकाशाला वर नाही आणि खाली नाही: भांडार तपासल्याशिवाय तुम्ही स्वागत कक्ष बदलू शकत नाही, आणि तारखा कशा छापायच्या यातला बदल timetable चे नियम मोडतो. Layer चा नियम इतका सोपा आहे की machine प्रत्येक push वर प्रत्येक import तपासू शकते — म्हणजे तुम्ही काढलेली रचना हीच तुमच्याकडची रचना राहते.

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

arch/analyze.py मधील layer_violations(g, order, strict) प्रत्येक मजल्याला order मधून क्रमांक देतो (वरचा आधी; default FLOORS = ["web", "app", "domain", "infra"]). दोन वेगवेगळ्या मजल्यांमधील प्रत्येक मार्गिकेसाठी: खालचा मजला वरच्याला import करत असेल तर ती upward; strict=True असताना एकापेक्षा जास्त मजले खाली जाणे म्हणजे skips a floor. कोणत्याही मजल्यावर नसलेल्या खोल्या (main, composition root) दुर्लक्षित केल्या जातात — सगळ्यांना ओळखण्याची परवानगी असलेली ती एकमेव खोली आहे.

🧪 करून पाहा

python3 arch/demo.py layers
python3 - <<'EOF'
import sys; sys.path.insert(0, "arch"); from analyze import scan, layer_violations
g = scan().imports
for order in (["web", "app", "domain", "infra"], ["web", "app", "infra", "domain"], ["web", "infra", "app", "domain"]):
    for strict in (False, True):
        v = layer_violations(g, order, strict)
        print(f"{' → '.join(order):<30} {'strict ' if strict else 'relaxed'} {len(v)} violation(s)")
EOF

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

layers हे छापतो:

── floors, top to bottom: web → app → domain → infra · a room may import its own floor or any floor BELOW
   relaxed layering: 4 violations
     domain.timetable → web.format (upward)
     infra.db → domain.grades (upward)
     infra.db → domain.ports (upward)
     infra.email → domain.ports (upward)
   strict layering (only the floor directly below): 5 violations — adds app.enrol → infra.email (skips a floor)

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

web → app → domain → infra     relaxed 4 violation(s)
web → app → domain → infra     strict  5 violation(s)
web → app → infra → domain     relaxed 2 violation(s)
web → app → infra → domain     strict  8 violation(s)
web → infra → app → domain     relaxed 3 violation(s)
web → infra → app → domain     strict  9 violation(s)

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

पारंपरिक क्रमाने (database सगळ्यात खाली) ऐश्वर्याला 4 वर जाणाऱ्या मार्गिका सापडतात — पण त्या नीट पाहा. त्यातल्या तीन म्हणजे infra.db आणि infra.email, जे त्यांना implement करायचे असलेले ports आणि परत द्यायचा असलेला Mark class import करतात. हा गोंधळ नाही; हा adapter आपले काम करतो आहे. पारंपरिक रचना domain ला database च्या वर बसायला भाग पाडते, म्हणून प्रत्येक adapter "चुकीचा" दिसतो. Domain सगळ्यात खाली ठेवा (web → app → infra → domain) आणि relaxed violations 2 वर येतात — खरोखर चुकीच्या असलेल्या दोन मार्गिका (domain.timetable → web.format आणि domain.grades → infra.db). मग strict layering 8 आणि 9 वर उडी मारते: domain सगळ्यात खाली असल्यामुळे प्रत्येक use case ला तिथे पोहोचण्यासाठी infra मजला "वगळावा" लागतो. Core तळाशी गेला की strict रचना नीट बसत नाही. मजल्यांचा क्रम हाच design निर्णय आहे.

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

database सगळ्यात खाली ठेवणे आणि मग business rules ना ORM वर अवलंबून ठेवणे
प्रत्येक technology साठी एक "layer" (controllers, services, repositories), आणि business rules तिन्हींमध्ये पसरलेले
सगळीकडे strict layering → काहीही न जोडणाऱ्या pass-through methods (sinkhole)
core import करतो असे वरच्या मजल्यावरचे सामायिक "helpers" (इथला day_name सारखे)
wiki वर लिहिलेला आणि कोणीही न तपासलेला layer चा नियम

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

On a real project — import-linter (Python) प्रत्येक run वर layers contract तपासतो. .importlinter मध्ये (किंवा pyproject.toml मधील [tool.importlinter] table मध्ये):

[importlinter]
root_package = schoolapp

[importlinter:contract:floors]
name = Floors only use the floors below
type = layers
layers =
    schoolapp.web
    schoolapp.app
    schoolapp.domain
    schoolapp.infra

pip install import-linter
lint-imports          # exits non-zero and lists each illegal import chain

ArchUnit (Java) हेच एका unit test मध्ये सांगतो:

@ArchTest
static final ArchRule floors = layeredArchitecture().consideringAllDependencies()
    .layer("Web").definedBy("..web..")
    .layer("App").definedBy("..app..")
    .layer("Domain").definedBy("..domain..")
    .layer("Infra").definedBy("..infra..")
    .whereLayer("Web").mayNotBeAccessedByAnyLayer()
    .whereLayer("App").mayOnlyBeAccessedByLayers("Web")
    .whereLayer("Domain").mayOnlyBeAccessedByLayers("App", "Web")
    .whereLayer("Infra").mayOnlyBeAccessedByLayers("Domain", "App", "Web");

JavaScript आणि TypeScript साठी dependency-cruiser हे forbidden नियमांनी करतो; .NET साठी NetArchTest.

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: मजल्यांचा क्रम हेतुपूर्वक निवडा — आणि database कुठे ठेवता ते लक्षात घ्या. Adapters सतत violations म्हणून दिसत असतील, तर तुमचा नियम तुमच्या design शी लढतो आहे. पुढचा धडा इमारत आतून बाहेर उलटवतो.

⏭️ पुढे

नियमपुस्तिका मजलाच नसून इमारतीचा मध्यभाग असती, आणि प्रत्येक दार बाहेरच्या दिशेने उघडत असते, तर? Ports and adapters.

git checkout lesson-04-hexagonal

🏢 Lesson 03 — Layers: floors, and which way the stairs go

📍 You are here: Lesson 03 of 12 · Previous: lesson-02-modularity · Next: lesson-04-hexagonal

📦 What's in this branch

Lessons 01–02, plus a rule. The classic layered architecture stacks the code in floors — web (presentation) on top, then app (use cases), then domain (business rules), then infra (database, email) at the bottom — with one rule: a floor may only use the floors below it. How to detect layer violations automatically, strict vs relaxed layering, and why this lesson ends with a surprise. layer_violations() in arch/analyze.py and layers() in arch/demo.py.

🧒 Explain like I'm 5

The school building has four floors. 🏢

Top floor — the reception (web): parents come in and ask questions.
Second floor — the office (app): staff who know how to do things — enrol a child, print a report card.
Third floor — the rule book (domain): what a mark is, how an average is worked out.
Ground floor — the store room and the post room (infra): the filing cabinets and the letters.

The rule: you may go down the stairs, never up. The office may look in the rule book. The rule book may not ring the reception to ask how to print a day name.

Aishwarya walks every corridor with a clipboard and writes down each one that goes up the stairs. That list is the layer violations.

🗺️ Diagram

flowchart TB
    web["🖥️ web — reception (top floor)"]
    app["🧑‍🏫 app — the office"]
    domain["📚 domain — the rule book"]
    infra["🔌 infra — store room + post room (ground floor)"]
    web -->|"ok: down"| app
    app -->|"ok: down"| domain
    domain -->|"ok: down"| infra
    domain -.->|"❌ upward: timetable → web.format"| web
    infra -.->|"❌ upward ×3: db → grades, db → ports, email → ports"| domain
    app -.->|"strict only: skips a floor (enrol → email)"| infra

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

❓ What

Layered architecture (n-tier) — the code is split into horizontal layers by kind of work. Eric Evans' Domain-Driven Design (2003) names four: user interface, application, domain, infrastructure. Many web apps use presentation, business, persistence, database.
The layering rule — a layer may depend only on layers below it. Nothing lower knows anything higher exists. Then you can change the top (a new mobile screen) without touching the bottom.
Relaxed (open) layering — any lower layer is fine; the web floor may go straight to the domain.
Strict (closed) layering — only the layer directly below. Every request passes through every floor. Cleaner, but it can create the architecture sinkhole anti-pattern (a name from Mark Richards): layers that only pass calls through without adding anything.
Layer violation — an import that breaks the rule: upward (lower imports higher) or, under strict layering, skipping a floor.
The dependency rule — Robert C. Martin's name (Clean Architecture) for "source code dependencies point only inwards, toward the policies". The next lesson shows that "inwards" and "downwards" are not the same thing — which is exactly this lesson's surprise.

🤔 Why

Because a floor plan with stairs in both directions has no top and no bottom: you cannot replace the reception without checking the store room, and a change to how dates are printed breaks the timetable rules. A layer rule is simple enough that a machine can check every import on every push — so the structure you drew stays the structure you have.

🔧 How (in this repo)

layer_violations(g, order, strict) in arch/analyze.py gives each floor a rank from order (top first; the default is FLOORS = ["web", "app", "domain", "infra"]). For each corridor between two different floors: a lower floor importing a higher one is upward; with strict=True, going down more than one floor is skips a floor. Rooms not on any floor (main, the composition root) are ignored — it is the one room allowed to know everyone.

🧪 Try it

python3 arch/demo.py layers
python3 - <<'EOF'
import sys; sys.path.insert(0, "arch"); from analyze import scan, layer_violations
g = scan().imports
for order in (["web", "app", "domain", "infra"], ["web", "app", "infra", "domain"], ["web", "infra", "app", "domain"]):
    for strict in (False, True):
        v = layer_violations(g, order, strict)
        print(f"{' → '.join(order):<30} {'strict ' if strict else 'relaxed'} {len(v)} violation(s)")
EOF

✅ Verify — what you should see

layers prints:

── floors, top to bottom: web → app → domain → infra · a room may import its own floor or any floor BELOW
   relaxed layering: 4 violations
     domain.timetable → web.format (upward)
     infra.db → domain.grades (upward)
     infra.db → domain.ports (upward)
     infra.email → domain.ports (upward)
   strict layering (only the floor directly below): 5 violations — adds app.enrol → infra.email (skips a floor)

Your snippet prints:

web → app → domain → infra     relaxed 4 violation(s)
web → app → domain → infra     strict  5 violation(s)
web → app → infra → domain     relaxed 2 violation(s)
web → app → infra → domain     strict  8 violation(s)
web → infra → app → domain     relaxed 3 violation(s)
web → infra → app → domain     strict  9 violation(s)

🏁 What you just proved

With the classic order (database at the bottom), Aishwarya finds 4 upward corridors — but look at them. Three are infra.db and infra.email importing the ports and the Mark class they need to implement and return. That is not a mess; that is an adapter doing its job. The classic stack forces the domain to sit on top of the database, so every adapter looks "wrong". Put the domain at the bottom (web → app → infra → domain) and relaxed violations drop to 2 — the two corridors that really are wrong (domain.timetable → web.format and domain.grades → infra.db). Strict layering then jumps to 8 and 9: with the domain at the bottom, every use case must "skip" the infra floor to reach it. A strict stack fits badly once the core is at the bottom. The order of the floors is the design decision.

⚠️ Common mistakes

putting the database at the bottom and then making business rules depend on the ORM
one "layer" per technology (controllers, services, repositories) with the business rules smeared across all three
strict layering everywhere → pass-through methods that add nothing (the sinkhole)
shared "helpers" on the top floor that the core imports (like day_name here)
a layer rule written on the wiki and checked by nobody

🏭 In production

On a real project — import-linter (Python) checks a layers contract on every run. In .importlinter (or the [tool.importlinter] table in pyproject.toml):

[importlinter]
root_package = schoolapp

[importlinter:contract:floors]
name = Floors only use the floors below
type = layers
layers =
    schoolapp.web
    schoolapp.app
    schoolapp.domain
    schoolapp.infra

pip install import-linter
lint-imports          # exits non-zero and lists each illegal import chain

ArchUnit (Java) says the same in a unit test:

@ArchTest
static final ArchRule floors = layeredArchitecture().consideringAllDependencies()
    .layer("Web").definedBy("..web..")
    .layer("App").definedBy("..app..")
    .layer("Domain").definedBy("..domain..")
    .layer("Infra").definedBy("..infra..")
    .whereLayer("Web").mayNotBeAccessedByAnyLayer()
    .whereLayer("App").mayOnlyBeAccessedByLayers("Web")
    .whereLayer("Domain").mayOnlyBeAccessedByLayers("App", "Web")
    .whereLayer("Infra").mayOnlyBeAccessedByLayers("Domain", "App", "Web");

For JavaScript and TypeScript, dependency-cruiser does it with forbidden rules; for .NET, NetArchTest.

🏭 Why this matters in production: pick the floor order on purpose — and notice where you put the database. If adapters keep showing up as violations, your rule is fighting your design. The next lesson turns the building inside out.

⏭️ Next

What if the rule book were not a floor at all, but the middle of the building, with every door facing out? Ports and adapters.

git checkout lesson-04-hexagonal

← Previousmodularity Next →hexagonal

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