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

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

🗺️ धडा 10 — C4 model: कॅम्पसचा नकाशा, इमारतीचा आराखडा, मजल्याचा नकाशा — code मधून काढलेले

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

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

धडे 01–09, आणि खरे सांगणारे documentation. C4 model एखादी system चार zoom levels वर काढते — Context, Containers, Components, Code — जसा कॅम्पसचा नकाशा, इमारतीचा आराखडा, मजल्याचा नकाशा आणि एका खोलीची मांडणी. Lab एक text C4 model तयार करते (Structurizr DSL) ज्याचे component arrows imports मधून येतात, आणि drift शोधण्यासाठी ते हाताने काढलेल्या wiki diagram शी तुलना करते. c4_dsl() आणि doc_drift() arch/analyze.py मध्ये, c4() arch/demo.py मध्ये.

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

ऐश्वर्या नावाची नवीन शिक्षिका शाळेत येते. 🧭 तिला शाळा कशी दाखवाल?

आधी, कॅम्पसचा नकाशा: ही आपली शाळा, हे भेटायला येणारे पालक, हे पोस्ट ऑफिस ज्यातून आपण पत्रे पाठवतो. (Context)
मग, इमारतीचा आराखडा: ही मुख्य इमारत, आणि तिच्या शेजारी ही नोंदींची खोली. (Containers)
मग, मुख्य इमारतीचा मजल्याचा नकाशा: स्वागत कक्ष, कार्यालय, नियमपुस्तिका, भांडार खोली — आणि त्यांच्यामधल्या मार्गिका. (Components)
तिने विचारले तरच: एका खोलीची मांडणी — प्रत्येक बाक कुठे आहे. (Code)

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

🗺️ आकृती

flowchart TB
    subgraph L1["1 · Context (the campus map)"]
      parent["👪 Parent"] --> school["🏫 School app"]
      staff["🧑‍💼 Office staff"] --> school
      school --> mail["✉️ Email service (external)"]
    end
    subgraph L2["2 · Containers (the building plan)"]
      webapp["Web app (Python)"] --> db[("Database")]
    end
    subgraph L3["3 · Components (the floor plan, from the imports)"]
      web["web"] -->|"3"| app["app"]
      app -->|"6"| domain["domain"]
      infra["infra"] -->|"3"| domain
      domain -.->|"1 · not on the wiki"| web
    end
    L1 --> L2 --> L3

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

❓ काय

C4 model — software architecture zoom करता येणाऱ्या diagrams च्या संचाच्या रूपात काढण्याची Simon Brown यांची पद्धत, छोट्या, ठरलेल्या शब्दसंग्रहासह:
1. System context — तुमची software system, ती वापरणारे लोक आणि ती ज्यांच्याशी बोलते त्या इतर systems.
2. Container — तुमच्या system मधल्या स्वतंत्रपणे चालणाऱ्या गोष्टी: web app, database, mobile app, queue. (इथे "Container" म्हणजे चालवता/deploy करता येणारे unit, Docker container असेलच असे नाही.)
3. Component — एका container च्या आतले मुख्य घटक आणि त्यांचे संबंध — इथे, web app चे चार मजले.
4. Code — classes आणि functions; सहसा IDE वर सोडले जाते.
पूरक views मध्ये system landscape, dynamic (एका request साठी क्रमांक दिलेला क्रम) आणि deployment diagrams येतात.
Diagrams as code — model ही repository मधली text file असते (Structurizr DSL, C4-PlantUML library सह PlantUML, किंवा Mermaid चे C4 diagrams), code सारखीच review होते आणि tool कडून render होते.
Model विरुद्ध view — Structurizr एकच model (elements आणि relationships) ठेवते आणि त्यातून अनेक views काढते, म्हणून एकाच box ला दोन चित्रांत दोन नावे असू शकत नाहीत.
Documentation drift — चित्र आणि code यांत मतभेद. चित्रातले arrows code मधून काढलेल्या arrows शी तुलना करून drift शोधला जातो.
arc42 — architecture documentation साठी मोठ्या प्रमाणावर वापरला जाणारा template (12 विभाग: goals, constraints, context, solution strategy, building blocks, runtime, deployment, concepts, decisions, quality, risks, glossary). C4 diagrams त्यात बसतात.

🤔 का

कारण बहुतेक architecture diagrams levels मिसळतात (class शेजारी database, त्याशेजारी व्यक्ती), असे boxes वापरतात ज्यांना कोणीच नाव देऊ शकत नाही, आणि काढल्यानंतरच्या आठवड्यातच जुने होतात. C4 पहिल्या दोन अडचणी ठरलेल्या zoom levels आणि छोट्या शब्दसंग्रहाने सोडवते. Component level code मधून तयार करणे — किंवा CI मध्ये तपासणे — तिसरी सोडवते.

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

arch/analyze.py मधले c4_dsl(g) एक Structurizr DSL workspace लिहिते: लोक, email system, containers आणि त्यांचे technology हाताने लिहिलेले आहेत (scanner ला ते कळू शकत नाहीत); components म्हणजे मजले आणि component relationships imports मधून मोजले जातात (app -> domain "imports (6)"). DOCUMENTED मध्ये wiki चित्रावरचे arrows आहेत. doc_drift(g) code मध्ये आहेत पण चित्रावर नाहीत असे arrows, आणि चित्रावर आहेत पण code मध्ये नाहीत असे arrows परत करते.

🧪 करून पाहा

python3 arch/demo.py c4
python3 - <<'EOF'
import sys; sys.path.insert(0, "arch"); from analyze import scan, c4_dsl, doc_drift, DOCUMENTED
g = scan().imports
print(c4_dsl(g))
print("wiki says:", DOCUMENTED)
print("in the code, not on the drawing:", doc_drift(g)[0])
EOF

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

c4 हे छापते:

── a C4 model as text (Structurizr DSL), 31 lines — the component arrows come from the code:
   app -> domain "imports (6)"
   app -> infra "imports (1)"
   domain -> infra "imports (1)"
   domain -> web "imports (1)"
   infra -> domain "imports (3)"
   web -> app "imports (3)"
   the wiki drawing is out of date: 3 arrows in the code are not on it: app → infra, domain → infra, domain → web
   after the fixes: 0 drift · generate the drawing from the code, or check it in CI

तुमचा snippet पूर्ण workspace छापतो — त्याची सुरुवात आणि शेवट असा होतो:

workspace "School app" {
  model {
    parent = person "Parent" "Checks report cards and pays fees"
    staff = person "Office staff" "Enrols students"
    mail = softwareSystem "Email service" "Sends welcome mails" "External"

  views {
    systemContext school { include * }
    container school { include * }
    component webapp { include * }
  }
}
wiki says: {'web': ['app'], 'app': ['domain'], 'infra': ['domain'], 'domain': []}
in the code, not on the drawing: [('app', 'infra'), ('domain', 'infra'), ('domain', 'web')]

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

Wiki चित्र स्वच्छ दृश्य दाखवते: web → app → domain ← infra. Code मध्ये आणखी तीन arrows आहेत — app → infra, domain → infra आणि domain → web — याच त्या मार्गिका ज्यांना धडे 03–04 ने उल्लंघने म्हटले. Wiki वाचणाऱ्या नवीन शिक्षिकेला domain स्वच्छ आहे असे वाटेल. तयार केलेले model drift होऊ शकत नाही, कारण ते imports मधून पुन्हा बनवले जाते; आणि fixes लागू झाल्यावर चित्र आणि code जुळतात (0 drift). Arrows वरचे आकडे (6, 3, 3, 1) मजल्यांमधली खरी वर्दळ कुठे आहे हे देखील दाखवतात.

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

सगळे levels एकत्र मिसळलेला एकच प्रचंड diagram
प्रकार किंवा technology नसलेले boxes ("Service", "Manager") आणि label नसलेले arrows
प्रत्येक container साठी component level काढणे — जिथे उपयोगी आहे तिथेच काढा
code शेजारी नव्हे तर slide deck मधले diagrams, म्हणून कोणीच ते अद्ययावत करत नाही
legend नसलेला diagram: रंग आणि आकारांचा अर्थ फक्त लेखिकेलाच माहीत असतो

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

खऱ्या machine वर — DSL Structurizr ने render करा. Lab चा output workspace.dsl म्हणून save करा आणि मोफत Structurizr Lite image चालवा, जी diagrams port 8080 वर दाखवते:

python3 -c 'import sys; sys.path.insert(0, "arch"); from analyze import scan, c4_dsl; print(c4_dsl(scan().imports))' > workspace.dsl
docker run -it --rm -p 8080:8080 -v "$PWD":/usr/local/structurizr structurizr/lite

हाच system context Mermaid मध्ये (त्याचे C4 diagrams experimental म्हणून चिन्हांकित आहेत), जो GitHub Markdown मध्येच render करते:

C4Context
  title School app — system context
  Person(parent, "Parent", "Checks report cards and pays fees")
  System(school, "School app", "Enrolment, marks, fees, timetable")
  System_Ext(mail, "Email service", "Sends welcome mails")
  Rel(parent, school, "Uses", "HTTPS")
  Rel(school, mail, "Sends mail", "SMTP")

Model repo मध्येच ठेवा (उदाहरणार्थ docs/architecture/workspace.dsl), आणि drift check धडा 09 च्या pipeline मध्ये जोडा, म्हणजे मजल्यांमधली नवीन मार्गिका चित्र (किंवा code) दुरुस्त होईपर्यंत fail होईल.

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: तुमच्या टीममधल्या सर्वात नवीन सदस्याला तुमचा architecture diagram दाखवा आणि तो कोणता level आहे ते विचारा. त्यांना सांगता आले नाही — किंवा तो code शी जुळतो याची तुम्हालाच खात्री नसेल — तर या आठवड्यात एक level code मधून तयार करा.

⏭️ पुढे

चित्रे इमारत काय आहे ते दाखवतात. जिना तिथेच का आहे हे ती कधीच सांगत नाहीत. Architecture decision records आणि trade-off analysis.

git checkout lesson-11-adrs

🗺️ Lesson 10 — The C4 model: campus map, building plan, floor plan — drawn from the code

📍 You are here: Lesson 10 of 12 · Previous: lesson-09-fitness-functions · Next: lesson-11-adrs

📦 What's in this branch

Lessons 01–09, plus documentation that tells the truth. The C4 model draws a system at four zoom levels — Context, Containers, Components, Code — like a campus map, a building plan, a floor plan and a room layout. The lab generates a text C4 model (Structurizr DSL) whose component arrows come from the imports, and compares it with the hand-drawn wiki diagram to find drift. c4_dsl() and doc_drift() in arch/analyze.py, c4() in arch/demo.py.

🧒 Explain like I'm 5

A new teacher, Aishwarya, joins the school. 🧭 How do you show her around?

First, the campus map: here is our school, here are the parents who visit, here is the post office we send letters through. (Context)
Then, the building plan: here is the main building, and here is the records room next to it. (Containers)
Then, the floor plan of the main building: reception, office, rule book, store room — and the corridors between them. (Components)
Only if she asks: the layout of one room — where each desk is. (Code)

You would never start with the desk layout. And one more thing: if the floor plan on the wall is old, it is worse than no plan — Aishwarya will walk into a wall. So Katrina prints the floor plan from the building itself, every time it changes.

🗺️ Diagram

flowchart TB
    subgraph L1["1 · Context (the campus map)"]
      parent["👪 Parent"] --> school["🏫 School app"]
      staff["🧑‍💼 Office staff"] --> school
      school --> mail["✉️ Email service (external)"]
    end
    subgraph L2["2 · Containers (the building plan)"]
      webapp["Web app (Python)"] --> db[("Database")]
    end
    subgraph L3["3 · Components (the floor plan, from the imports)"]
      web["web"] -->|"3"| app["app"]
      app -->|"6"| domain["domain"]
      infra["infra"] -->|"3"| domain
      domain -.->|"1 · not on the wiki"| web
    end
    L1 --> L2 --> L3

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

❓ What

C4 model — Simon Brown's way to draw software architecture as a set of zoomable diagrams, with a small, fixed vocabulary:
1. System context — your software system, the people who use it and the other systems it talks to.
2. Container — the separately running things inside your system: a web app, a database, a mobile app, a queue. ("Container" here means a runnable/deployable unit, not necessarily a Docker container.)
3. Component — the main building blocks inside one container and their relationships — here, the four floors of the web app.
4. Code — classes and functions; usually left to the IDE.
Supporting views include a system landscape, dynamic (a numbered sequence for one request) and deployment diagrams.
Diagrams as code — the model is a text file in the repository (Structurizr DSL, PlantUML with the C4-PlantUML library, or Mermaid's C4 diagrams), reviewed like code and rendered by a tool.
Model vs view — Structurizr keeps one model (elements and relationships) and derives many views from it, so the same box cannot have two names in two drawings.
Documentation drift — the drawing and the code disagree. Drift is detected by comparing the drawing's arrows with arrows extracted from the code.
arc42 — a widely used template for architecture documentation (12 sections: goals, constraints, context, solution strategy, building blocks, runtime, deployment, concepts, decisions, quality, risks, glossary). C4 diagrams fit inside it.

🤔 Why

Because most architecture diagrams mix levels (a database next to a class next to a person), use boxes nobody can name, and are out of date the week after they are drawn. C4 fixes the first two with fixed zoom levels and a small vocabulary. Generating the component level from the code — or checking it in CI — fixes the third.

🔧 How (in this repo)

c4_dsl(g) in arch/analyze.py writes a Structurizr DSL workspace: the people, the email system, the containers and their technology are written by hand (a scanner cannot know them); the components are the floors and the component relationships are counted from the imports (app -> domain "imports (6)"). DOCUMENTED holds the arrows on the wiki drawing. doc_drift(g) returns the arrows in the code but not on the drawing, and the arrows on the drawing but not in the code.

🧪 Try it

python3 arch/demo.py c4
python3 - <<'EOF'
import sys; sys.path.insert(0, "arch"); from analyze import scan, c4_dsl, doc_drift, DOCUMENTED
g = scan().imports
print(c4_dsl(g))
print("wiki says:", DOCUMENTED)
print("in the code, not on the drawing:", doc_drift(g)[0])
EOF

✅ Verify — what you should see

c4 prints:

── a C4 model as text (Structurizr DSL), 31 lines — the component arrows come from the code:
   app -> domain "imports (6)"
   app -> infra "imports (1)"
   domain -> infra "imports (1)"
   domain -> web "imports (1)"
   infra -> domain "imports (3)"
   web -> app "imports (3)"
   the wiki drawing is out of date: 3 arrows in the code are not on it: app → infra, domain → infra, domain → web
   after the fixes: 0 drift · generate the drawing from the code, or check it in CI

Your snippet prints the whole workspace — it starts and ends like this:

workspace "School app" {
  model {
    parent = person "Parent" "Checks report cards and pays fees"
    staff = person "Office staff" "Enrols students"
    mail = softwareSystem "Email service" "Sends welcome mails" "External"

  views {
    systemContext school { include * }
    container school { include * }
    component webapp { include * }
  }
}
wiki says: {'web': ['app'], 'app': ['domain'], 'infra': ['domain'], 'domain': []}
in the code, not on the drawing: [('app', 'infra'), ('domain', 'infra'), ('domain', 'web')]

🏁 What you just proved

The wiki drawing shows a clean picture: web → app → domain ← infra. The code has three more arrows — app → infra, domain → infra and domain → web — the very corridors lessons 03–04 called violations. A new teacher reading the wiki would believe the domain is clean. The generated model cannot drift, because it is rebuilt from the imports; and once the fixes are applied, the drawing and the code agree (0 drift). The counts on the arrows (6, 3, 3, 1) also show where the real traffic between floors is.

⚠️ Common mistakes

one giant diagram with every level mixed together
boxes with no type or technology ("Service", "Manager") and arrows with no label
drawing the component level for every container — draw it only where it helps
diagrams in a slide deck, not next to the code, so nobody updates them
a legend-free diagram: colours and shapes mean something to the author only

🏭 In production

On a real machine — render the DSL with Structurizr. Save the lab's output as workspace.dsl and run the free Structurizr Lite image, which serves the diagrams on port 8080:

python3 -c 'import sys; sys.path.insert(0, "arch"); from analyze import scan, c4_dsl; print(c4_dsl(scan().imports))' > workspace.dsl
docker run -it --rm -p 8080:8080 -v "$PWD":/usr/local/structurizr structurizr/lite

The same system context in Mermaid (its C4 diagrams are marked experimental), which GitHub renders inside Markdown:

C4Context
  title School app — system context
  Person(parent, "Parent", "Checks report cards and pays fees")
  System(school, "School app", "Enrolment, marks, fees, timetable")
  System_Ext(mail, "Email service", "Sends welcome mails")
  Rel(parent, school, "Uses", "HTTPS")
  Rel(school, mail, "Sends mail", "SMTP")

Keep the model in the repo (for example docs/architecture/workspace.dsl), and add the drift check to the lesson 09 pipeline so a new corridor between floors fails until the drawing (or the code) is fixed.

🏭 Why this matters in production: show your team's newest joiner your architecture diagram and ask which level it is. If they cannot tell — or if you are not sure it matches the code — generate one level from the code this week.

⏭️ Next

The drawings show what the building is. They never say why the staircase is where it is. Architecture decision records and trade-off analysis.

git checkout lesson-11-adrs

← Previousfitness functions Next →adrs

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