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

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

🗂️ धडा 05 — Domain-driven design: स्वतःचे शब्द असलेले विभाग

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

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

धडे 01–04, आणि विभाग. शाळा म्हणजे एक मोठी नियमपुस्तिका नव्हे — ती आहे एक प्रवेश कार्यालय, एक परीक्षा विभाग, एक लेखा कार्यालय आणि एक वेळापत्रक कार्यालय, आणि प्रत्येक जण तेच शब्द वेगळ्या अर्थाने वापरतो. Domain-driven design (DDD) प्रत्येकाभोवती एक bounded context आखते, त्याच्या आत एक ubiquitous language बोलते, आणि ते एकमेकांशी कसे जोडलेले आहेत याचा context map काढते. Lab हा context map code मधून वाचतो: arch/analyze.py मधील CONTEXTS आणि context_edges(), arch/demo.py मधील ddd().

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

तीन offices ना विचारा "student म्हणजे काय?" 🤔

प्रवेश कार्यालय म्हणते: "एक form क्रमांक, एक नाव, आणि आम्ही प्रवेश दिला की नाही."
परीक्षा विभाग म्हणतो: "maths आणि science मधले marks असलेला एक roll क्रमांक."
लेखा कार्यालय म्हणते: "fees देणे बाकी असलेले एक खाते."

तिघेही बरोबर आहेत — आपापल्या office च्या आत. गडबड तेव्हा सुरू होते जेव्हा परीक्षा विभाग प्रवेश कार्यालयाची student ची कल्पना उसनी घेतो. आता प्रवेश कार्यालयाने आपल्या form मध्ये एक नवा रकाना जोडला की परीक्षा विभागाचे report cards बिघडू शकतात, आणि परीक्षा विभागात कोणीही काहीच बदललेले नसते.

म्हणून प्रत्येक office student ची स्वतःची कल्पना स्वतःच्या शब्दांत ठेवते. परीक्षा विभागाला प्रवेश कार्यालयाकडून नाव हवे असेल, तेव्हा दारावर कोणीतरी अनुवाद करते: "तुमचा अर्जदार क्रमांक 1042 म्हणजे आमचा roll क्रमांक 7." तो अनुवादक म्हणजे anti-corruption layer.

🗺️ आकृती

flowchart LR
    adm["🗂️ admissions<br/>Student = form no, name, status"]
    gr["📝 grades (exam cell)<br/>student = roll no + marks"]
    fee["💰 fees (accounts)<br/>student = an account"]
    tt["🗓️ timetable<br/>periods and rooms"]
    gr -->|"imports Student · conformist today<br/>→ anti-corruption layer"| adm
    fee -->|"imports Student · customer–supplier"| adm

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

❓ काय

Domain-driven design (DDD) — Eric Evans यांचा दृष्टिकोन (Domain-Driven Design, 2003): software चा model व्यवसायावर, व्यवसायाच्याच शब्दांत बांधा, आणि मोठे models लहान, सुसंगत models मध्ये विभागा.
Domain / subdomain — व्यवसायाचे क्षेत्र (शाळा चालवणे) आणि त्याचे भाग (admissions, परीक्षा, fees, वेळापत्रक). Core subdomains तुम्हाला वेगळे ठरवतात; supporting आणि generic subdomains (payments, email) तुम्ही कदाचित विकत घ्याल.
Bounded context — अशी सीमा जिच्या आत एक model आणि एकच शब्दसंच सुसंगतपणे लागू होतो. तिच्या बाहेर तोच शब्द वेगळे काहीतरी म्हणू शकतो — आणि ते ठीक आहे.
Ubiquitous language — एका bounded context चा सामायिक शब्दसंग्रह, जो तज्ज्ञ आणि code (class ची नावे, method ची नावे, events) दोघेही वापरतात.
Context map — bounded contexts आणि ते एकमेकांशी कसे जोडलेले आहेत याचे चित्र. Evans यांनी या नात्यांना नावे दिली; त्यातली काही:
- customer–supplier — downstream टीमच्या गरजा upstream च्या नियोजनात विचारात घेतल्या जातात
- conformist — downstream upstream चा model जसाच्या तसा वापरतो
- anti-corruption layer (ACL) — downstream सीमेवर upstream च्या model चा स्वतःच्या model मध्ये अनुवाद करतो
- shared kernel — दोन टीम वाटून घेतात आणि फक्त एकत्रच बदलतात असा छोटा model
- open host service / published language — upstream सगळ्यांसाठी एक स्थिर, दस्तऐवजीकरण केलेला interface देतो
- separate ways — कोणतेही integration नाही
Upstream / downstream — कोण कोणाला मोडू शकतो: downstream upstream वर अवलंबून असतो.

🤔 का

कारण संपूर्ण शाळेसाठी एकच model म्हणजे चाळीस fields असलेला Student class, जो प्रत्येक office edit करते आणि कोणाचीच मालकी नसते. Bounded contexts मुळे प्रत्येक विभाग संपूर्ण शाळेच्या meeting शिवाय आपले नियम बदलू शकतो — म्हणजे प्रत्येक विभागासाठी modifiability. नंतर code तोडण्यासाठीचे (धडा 06) ते नैसर्गिक सांधेही आहेत: विभागांनुसार तोडा, मजल्यांनुसार नव्हे.

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

arch/analyze.py मधील CONTEXTS प्रत्येक विभागाला त्याच्या खोल्यांशी जोडतो (grades कडे domain.grades, app.report_card आणि infra.db ची मालकी). context_edges(g, names) एका विभागातून दुसऱ्या विभागात जाणारी प्रत्येक मार्गिका, import केलेल्या नावांसह, सूचीबद्ध करतो — scan() ती प्रत्येक from … import … मधून नोंदवतो. Demo मधील "student" चे अर्थ हाताने लिहिलेले आहेत (भाषा माणूस ठरवतो, scanner नव्हे); edges मात्र code मधून वाचले जातात.

🧪 करून पाहा

python3 arch/demo.py ddd
python3 - <<'EOF'
import sys; sys.path.insert(0, "arch"); from analyze import scan, CONTEXTS, context_edges, apply
cb = scan(); g = cb.imports
for c, rooms in CONTEXTS.items():
    print(f"{c:<10} rooms {rooms} · classes {[k for r in rooms for k, _ in cb.classes[r]]}")
print("cross-department corridors:", len(context_edges(g, cb.names)))
acl = apply(g, remove=[("domain.grades", "domain.admissions"), ("domain.fees", "domain.admissions")])
print("after each department keeps its own Student:", len(context_edges(acl)))
EOF

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

ddd हे छापतो:

── the context map, read from the code: 2 cross-department corridors
   fees → admissions: domain.fees imports Student from domain.admissions
   grades → admissions: domain.grades imports Student from domain.admissions

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

admissions rooms ['domain.admissions', 'app.enrol'] · classes ['Student', 'Application', 'EnrolService']
grades     rooms ['domain.grades', 'app.report_card', 'infra.db'] · classes ['Mark', 'ReportCard', 'ReportCardService', 'SqlGradeStore', 'SqlLedger']
fees       rooms ['domain.fees', 'app.fees_service'] · classes ['Account', 'FeesService']
timetable  rooms ['domain.timetable'] · classes ['Period']
cross-department corridors: 2
after each department keeps its own Student: 0

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

Context map म्हणजे whiteboard वरची इच्छा नव्हे — तो imports मधून वाचता येतो. दोन विभाग एकाच class साठी, Student, admissions मध्ये हात घालतात. दोघांनाही फक्त नाव हवे आहे, पण आता admissions ने आपला model बदलला की दोघेही बदलतात. प्रत्येक विभागाला student ची स्वतःची छोटी कल्पना द्या (आणि दारावर अनुवाद करा) आणि विभाग-ओलांडणाऱ्या मार्गिका 2 वरून 0 वर येतात. यादीत दिसणारी एक विचित्र गोष्ट लक्षात घ्या: SqlLedger grades विभागाच्या infra.db मध्ये राहतो, पण तो fees ची सेवा करतो. File technology नुसार मांडलेली आहे, विभागानुसार नव्हे. तुम्ही विभागांनुसार तोडता, तेव्हा ती file ही तुटते.

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

संपूर्ण कंपनीसाठी एकच सामायिक Student (किंवा User, Order) model
bounded contexts व्यवसायाच्या रेषांऐवजी तांत्रिक रेषांवर (एक "database context") आखणे
संपूर्ण model होईपर्यंत वाढत जाणारा "shared kernel"
"आज fields सारखेच दिसतात" म्हणून अनुवाद वगळणे
काम करणाऱ्या लोकांकडून भाषा शिकण्याऐवजी ती code मध्ये शोधून काढणे

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

On a real project — anti-corruption layer म्हणजे बहुतेकदा downstream विभागाच्या मालकीचे फक्त एक छोटे अनुवादक module:

# grades/acl/admissions.py — the only file in grades that knows admissions' model
from dataclasses import dataclass
from admissions.api import get_student          # the upstream's published interface

@dataclass(frozen=True)
class Learner:                                  # grades' own word
    roll_no: int
    display_name: str

def learner_for(roll_no: int) -> Learner:
    s = get_student(roll_no)                    # upstream shape: form_no, full_name, status…
    return Learner(roll_no=roll_no, display_name=s["full_name"])

विभागांना top-level packages बनवा (schoolapp/admissions/, schoolapp/grades/ …) आणि import-linter ला त्यांना वेगळे ठेवू द्या, फक्त प्रत्येक विभागाच्या api module ला परवानगी देऊन:

[importlinter:contract:departments]
name = Departments talk only through their api
type = independence
modules =
    schoolapp.admissions
    schoolapp.grades
    schoolapp.fees
    schoolapp.timetable
ignore_imports =
    schoolapp.grades.acl.admissions -> schoolapp.admissions.api

Contexts शोधणे ही workshop आहे, script नव्हे: Event Storming (Alberto Brandolini) domain तज्ज्ञ आणि developers ना sticky notes च्या एका लांब भिंतीसमोर उभे करते, प्रत्येक business event साठी एक note, आणि जिथे शब्द बदलतात तिथे सीमा दिसू लागतात.

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: तुमचे सगळ्यात जास्त import होणारे पाच classes लिहा. प्रत्येकासाठी तीन विभागांना विचारा की त्या शब्दाचा अर्थ काय. दोन वेगळी उत्तरे म्हणजे दोन models.

⏭️ पुढे

विभाग म्हणजे सांधे. ते एकाच इमारतीत राहतात, की campus भर वेगवेगळ्या इमारतींत? Monolith, modular monolith, microservices — आणि प्रत्येकाची किंमत.

git checkout lesson-06-styles

🗂️ Lesson 05 — Domain-driven design: departments with their own words

📍 You are here: Lesson 05 of 12 · Previous: lesson-04-hexagonal · Next: lesson-06-styles

📦 What's in this branch

Lessons 01–04, plus departments. The school is not one big rule book — it is an admissions office, an exam cell, an accounts office and a timetable office, and each one uses the same words differently. Domain-driven design (DDD) draws a bounded context around each, speaks a ubiquitous language inside it, and draws a context map of how they relate. The lab reads the context map from the code: CONTEXTS and context_edges() in arch/analyze.py, ddd() in arch/demo.py.

🧒 Explain like I'm 5

Ask three offices "what is a student?" 🤔

The admissions office says: "a form number, a name, and whether we accepted them."
The exam cell says: "a roll number with marks in maths and science."
The accounts office says: "an account that owes fees."

All three are right — inside their own office. Trouble starts when the exam cell borrows the admissions office's idea of a student. Now, when admissions adds a new box to its form, the exam cell's report cards can break, and nobody in the exam cell changed anything.

So each office keeps its own idea of a student, in its own words. When the exam cell needs a name from admissions, someone at the door translates: "your applicant number 1042 is our roll number 7." That translator is an anti-corruption layer.

🗺️ Diagram

flowchart LR
    adm["🗂️ admissions<br/>Student = form no, name, status"]
    gr["📝 grades (exam cell)<br/>student = roll no + marks"]
    fee["💰 fees (accounts)<br/>student = an account"]
    tt["🗓️ timetable<br/>periods and rooms"]
    gr -->|"imports Student · conformist today<br/>→ anti-corruption layer"| adm
    fee -->|"imports Student · customer–supplier"| adm

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

❓ What

Domain-driven design (DDD) — Eric Evans' approach (Domain-Driven Design, 2003): model the software on the business, in the business's words, and split big models into smaller consistent ones.
Domain / subdomain — the business area (running a school) and its parts (admissions, exams, fees, timetabling). Core subdomains are what make you special; supporting and generic ones (payments, email) you might buy.
Bounded context — a boundary inside which one model and one set of words apply consistently. Outside it, the same word may mean something else — and that is fine.
Ubiquitous language — the shared vocabulary of one bounded context, used by the experts and in the code (class names, method names, events).
Context map — a drawing of the bounded contexts and how they relate. Evans named the relationships; some of them:
- customer–supplier — the downstream team's needs count in the upstream's planning
- conformist — the downstream simply uses the upstream's model as it is
- anti-corruption layer (ACL) — the downstream translates the upstream's model into its own at the boundary
- shared kernel — a small model two teams share and change only together
- open host service / published language — the upstream offers a stable, documented interface for everyone
- separate ways — no integration at all
Upstream / downstream — who can break whom: the downstream depends on the upstream.

🤔 Why

Because one model for the whole school becomes a Student class with forty fields that every office edits and nobody owns. Bounded contexts let each department change its rules without a school-wide meeting — which is modifiability, per department. They are also the natural seams for splitting code later (lesson 06): split along departments, not along floors.

🔧 How (in this repo)

CONTEXTS in arch/analyze.py maps each department to its rooms (grades owns domain.grades, app.report_card and infra.db). context_edges(g, names) lists every corridor that crosses from one department to another, with the names imported — scan() records them from each from … import …. The meanings of "student" in the demo are written by hand (a person decides a language, not a scanner); the edges are read from the code.

🧪 Try it

python3 arch/demo.py ddd
python3 - <<'EOF'
import sys; sys.path.insert(0, "arch"); from analyze import scan, CONTEXTS, context_edges, apply
cb = scan(); g = cb.imports
for c, rooms in CONTEXTS.items():
    print(f"{c:<10} rooms {rooms} · classes {[k for r in rooms for k, _ in cb.classes[r]]}")
print("cross-department corridors:", len(context_edges(g, cb.names)))
acl = apply(g, remove=[("domain.grades", "domain.admissions"), ("domain.fees", "domain.admissions")])
print("after each department keeps its own Student:", len(context_edges(acl)))
EOF

✅ Verify — what you should see

ddd prints:

── the context map, read from the code: 2 cross-department corridors
   fees → admissions: domain.fees imports Student from domain.admissions
   grades → admissions: domain.grades imports Student from domain.admissions

Your snippet prints:

admissions rooms ['domain.admissions', 'app.enrol'] · classes ['Student', 'Application', 'EnrolService']
grades     rooms ['domain.grades', 'app.report_card', 'infra.db'] · classes ['Mark', 'ReportCard', 'ReportCardService', 'SqlGradeStore', 'SqlLedger']
fees       rooms ['domain.fees', 'app.fees_service'] · classes ['Account', 'FeesService']
timetable  rooms ['domain.timetable'] · classes ['Period']
cross-department corridors: 2
after each department keeps its own Student: 0

🏁 What you just proved

The context map is not a wish on a whiteboard — it can be read from the imports. Two departments reach into admissions for the same class, Student. Both need only a name, but both now change whenever admissions changes its model. Give each department its own small idea of a student (and translate at the door) and the cross-department corridors drop from 2 to 0. Notice one oddity the listing shows: SqlLedger lives in the grades department's infra.db, but it serves fees. The file is organised by technology, not by department. When you split along departments, that file splits too.

⚠️ Common mistakes

one shared Student (or User, Order) model for the whole company
drawing bounded contexts along technical lines (a "database context") instead of business ones
a "shared kernel" that grows until it is the whole model
skipping the translation because "the fields look the same today"
inventing the language in the code instead of learning it from the people who do the work

🏭 In production

On a real project — an anti-corruption layer is often just a small translator module owned by the downstream department:

# grades/acl/admissions.py — the only file in grades that knows admissions' model
from dataclasses import dataclass
from admissions.api import get_student          # the upstream's published interface

@dataclass(frozen=True)
class Learner:                                  # grades' own word
    roll_no: int
    display_name: str

def learner_for(roll_no: int) -> Learner:
    s = get_student(roll_no)                    # upstream shape: form_no, full_name, status…
    return Learner(roll_no=roll_no, display_name=s["full_name"])

Make departments top-level packages (schoolapp/admissions/, schoolapp/grades/ …) and let import-linter keep them apart, allowing only each department's api module:

[importlinter:contract:departments]
name = Departments talk only through their api
type = independence
modules =
    schoolapp.admissions
    schoolapp.grades
    schoolapp.fees
    schoolapp.timetable
ignore_imports =
    schoolapp.grades.acl.admissions -> schoolapp.admissions.api

Finding the contexts is a workshop, not a script: Event Storming (Alberto Brandolini) puts the domain experts and developers in front of a long wall of sticky notes, one per business event, and the boundaries show up where the words change.

🏭 Why this matters in production: list your five most imported classes. For each, ask three departments what the word means. Two different answers means two models.

⏭️ Next

Departments are the seams. Do they live in one building, or in separate buildings across campus? Monolith, modular monolith, microservices — and what each one costs.

git checkout lesson-06-styles

← Previoushexagonal Next →styles

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