Modules, Boundaries, and Coupling
The only architecture question that matters is what knows about what — carving TraceLab's God module apart.
🎯 By the end you'll understand
What coupling, cohesion, afferent/efferent metrics, and the Stable Dependencies Principle actually measure — and why they matter in Python, where the import system makes every circular reference a subtle lie waiting to explode. You will apply these ideas surgically to TraceLab v2's real God module, run the coupling graph editor, and understand why the damage from bad boundaries is invisible until feature number three.
KEY INSIGHTArchitecture is recorded dependency decisions
Every architectural decision reduces to one question: which module is allowed to know about which other module? Get that wrong, and every future change touches every file.
You have spent three stages adding capability to TraceLab. The server knows about the CSV storage. The ingest path knows about the dashboard format. The CLI knows about the database schema. Nobody planned any of this — it accreted. And now TraceLab v2 has a God module: a single file that knows about everything, and that therefore must change whenever anything changes. This lesson is about making that structure visible so you can cut it.
Bad module boundaries are invisible for the first two features. The third feature is where they announce themselves: suddenly every change touches every file, because the knowledge flows the wrong way. The damage was done on day one — you just couldn't see it yet. Dependency direction is architecture's load-bearing wall, and you cannot see the wall if you never drew the map.
CORE CONCEPTCoupling, cohesion, and the metrics that make them countable
Two concepts have been in software engineering since the 1970s — Larry Constantine and Ed Yourdon formalized them in Structured Design (1979) — and they survive because they are genuinely measuring something real:
- Cohesion is the degree to which the elements inside a module belong together. High cohesion: one module, one job. Low cohesion: a module that does logging, HTTP routing, schema migration, and email — a junk drawer.
- Coupling is the degree to which one module depends on another. The goal is not zero coupling (that would be no program) but directional coupling: dependencies flow one way, from volatile toward stable, and never circle back.
Robert Martin formalized coupling into two countable metrics that apply cleanly to Python import graphs:
| Metric | Definition | Intuition | Target |
|---|---|---|---|
| Afferent coupling (Ca) | How many modules import this module | "How many things depend on me?" | High is fine — if the module is stable |
| Efferent coupling (Ce) | How many modules this module imports | "How many things can break me?" | Low preferred for volatile modules |
| Instability (I) | Ce / (Ca + Ce) | 0 = maximally stable; 1 = maximally volatile | Volatile modules should do the importing |
The Stable Abstractions Principle (SAP) says a module's level of abstraction should increase with its stability. Put concretely: the modules that define your domain concepts (what a Run is, what an Experiment is) should be maximally stable and abstract — they depend on nothing inside your system. The modules that implement HTTP routes or CSV file formats are volatile and concrete; they should depend on the stable core, not the other way around.
The complementary metric to coupling is cohesion. Robert Martin's Reuse-Release Equivalence Principle offers a useful test: can you describe what this module does in one sentence without the word "and"? If your sentence is "handles HTTP requests and parses CSV files and logs errors," you have three modules that got glued together by accident. Split them. If every function in the module works with the same data and toward the same purpose, cohesion is high. That shared purpose is your module's boundary.
CORE CONCEPTStable vs volatile: the asymmetry that drives everything
Not all modules are created equal. Some modules represent stable abstractions — the concepts that barely change once the domain is understood. Others are volatile concretions — implementation details that change every time a technology or a requirement shifts. The key architectural discipline is placing stable modules at the dependency root (nothing inside the system points at them, but they define what everything else depends on) and volatile modules at the leaves (they do the importing; they are the ones that change).
In TraceLab's case, the decomposition is not arbitrary. You can derive it by asking which concepts survive a complete technology swap:
domain — the universal stable core
The concept of a Run (an experiment with a name, metrics, and a timestamp) exists regardless of whether you store it in a CSV, a SQLite database, or Postgres. It doesn't import anything from the rest of your system. Ca can be high; Ce should be zero inside the system. This is the nucleus.
storage — stable shape, volatile implementation
A storage module knows the domain types and defines an interface for persistence. The concrete CSV implementation lives here, but the interface it satisfies belongs at the domain boundary. Storage imports domain; nothing imports storage's CSV internals directly.
ingest — volatile consumer
The ingest path knows how to receive a log event, validate it against the domain types, and persist it via the storage interface. It imports both domain and storage. It is volatile: when the network protocol changes, ingest changes. That's fine — it's a leaf.
api — volatile presenter
The HTTP API reads runs from storage and serializes them to JSON. It imports domain and storage. It does not import ingest (one-way data flow: ingest writes, api reads). It is volatile: when the response schema changes, only api changes. Nothing else moves.
This is not four arbitrary buckets. It is a directed acyclic graph — domain at the root, ingest and api at the leaves — where every edge points toward stability. If you achieve it, you can replace the CSV backend with SQLite by touching only storage/csv.py. You can replace Flask with FastAPI by touching only api/routes.py. The domain never even knows the swap happened.
CORE CONCEPTCycles are cancer
A circular dependency — module A imports B, B imports C, C imports A — looks like a curiosity in small codebases and a catastrophe in large ones. Let's be precise about why.
In Python, when you run python tracelab.py, the interpreter walks the import graph, executing each module's top-level code exactly once and memoizing it in sys.modules. A cycle means that when module A is being imported, it tries to import B, which tries to import C, which tries to import A — but A is already in sys.modules as a partially initialized module object. The names that A defined before it triggered the cycle exist; the ones defined after it don't yet. The result is an ImportError or, worse, a subtly incorrect object that has some attributes and not others, depending on import order.
# tracelab.py — the God module. Everything imports this. # storage.py imports tracelab for the Run type. # api.py imports tracelab for the Run type AND for the storage functions. # ingest.py imports tracelab for log_run() AND the Run type. # tracelab.py imports all of them "to keep things together." # Congratulations, you have a 4-way cycle. import storage # storage imports us — partial init problem waiting import api # api imports us AND storage import ingest # ingest imports us AND storage class Run: # defined here — after the circular imports above __init__ = lambda self, name, metrics: None # not reached on cycle
The canonical fix is not "use import-inside-function to break the cycle." That is a suppressor, not a cure — it hides the symptom by deferring the import to call time, which makes performance unpredictable and dependency tracking impossible. The real fix is inverting the direction: the domain types move to a module that imports nothing from the system. Every other module imports domain; domain imports nobody. The cycle cannot form because the graph has a root.
Every language with a module system has this problem. Go's compiler refuses circular imports at build time. Java's linker will load them but give you null-initialized statics. Python silently gives you partially-initialized modules. The Python behavior is arguably the most dangerous because it doesn't immediately fail — it just returns wrong objects. If your code has a cycle and "seems to work," count on it breaking under a future refactor that changes import order.
Beyond the mechanics, there's a deeper point: a cycle means two modules that cannot be understood in isolation. If A and B form a cycle, you cannot reason about A without knowing B and vice versa — you've created a single logical component with two physical files. Either merge them (accept the logical unity) or invert the dependency (extract the shared concept into a third module both can import).
SEE ITRewire TraceLab's module graph
The widget below shows TraceLab v2's actual dependency situation before the Stage 4 refactor. The God module (tracelab.py) sits at the center and knows about everything. Your job is to rewire the graph by clicking buttons to move responsibilities and remove or add edges until you reproduce the clean target layout: domain → storage → (ingest, api). The metrics update live, cycle detection runs on every change, and the "cost of change" probe shows how many modules a single change propagates to.
Two things to notice while you run through the steps. First, the "cost of change" probe for tracelab (the God module) in the v2 state touches all five modules — every change propagates everywhere. After step 1, the probe for domain touches only itself: it is at the root and nothing it depends on can change (it has no dependencies). Second, the cycle count drops to zero after step 2, and the average instability drops sharply as the graph acquires the correct direction from stable to volatile.
TRACELABCarving the God module: the actual cut
This is what the v2-to-v3 migration looks like in practice. TraceLab v2 has a single tracelab.py that contains the Run dataclass, the CSV read/write functions, the Flask routes, and the ingest handler. Everything imports everything. The v3 target is four files with clean boundaries.
Start with the domain layer — the move that makes all other moves possible:
from __future__ import annotations from dataclasses import dataclass, field from datetime import datetime from typing import Dict, Any @dataclass class Run: """A single experiment run. This concept is independent of storage format, HTTP protocol, or any infrastructure detail. It is the vocabulary of the whole system — everything else imports this; this imports nothing internal.""" name: str metrics: Dict[str, Any] recorded_at: datetime = field(default_factory=datetime.utcnow) run_id: str = field(default_factory=lambda: _new_id()) def _new_id() -> str: # deterministic-looking in tests if you patch datetime; no import of random import hashlib return hashlib.md5(str(datetime.utcnow()).encode()).hexdigest()[:8]
With domain.py extracted, the storage layer gets a clean contract. It imports domain.Run; it does not import api or ingest:
from __future__ import annotations import csv, io, pathlib from datetime import datetime from typing import List, Optional from .domain import Run # the ONLY internal import _DEFAULT_PATH = pathlib.Path("runs.csv") def append_run(run: Run, path: pathlib.Path = _DEFAULT_PATH) -> None: with path.open("a", newline="", encoding="utf-8") as f: w = csv.writer(f) w.writerow([run.run_id, run.name, run.recorded_at.isoformat(), str(run.metrics)]) def find_run(run_id: str, path: pathlib.Path = _DEFAULT_PATH) -> Optional[Run]: if not path.exists(): return None with path.open(encoding="utf-8") as f: for row in csv.reader(f): if row and row[0] == run_id: # exact match, not substring return Run(name=row[1], recorded_at=datetime.fromisoformat(row[2]), metrics=eval(row[3]), # Lesson 4.8 pays this debt run_id=row[0]) return None
The ingest and API layers are now leaves — they import domain and storage, but nothing imports them except the application entry point:
from .domain import Run from . import storage def record(name: str, metrics: dict) -> Run: run = Run(name=name, metrics=metrics) storage.append_run(run) return run
The v3 storage module fixes the two most dangerous v0 sins: values are stored in proper CSV columns (not string-glued with +), and lookups match run_id exactly (not name in line substring). It does not fix the eval()-for-metrics debt — that waits until the schema migration lesson, where we replace the CSV with a real format as part of a zero-downtime expand-contract migration. Keep the debt ledger honest.
This decomposition is the Stage 4 milestone for TraceLab: v3 is the same behaviour as v2, but the internal structure has been made explicit and directional. Every future lesson in this stage adds one architectural layer — ingest queue, cache, security hardening, zero-downtime migration — and each one touches exactly the modules it logically should, because the boundaries are now real.
WEAKNESSWhere this bites
The damage from wrong boundaries is not linear. In TraceLab v2 with the God module, adding a single new feature — say, a webhook notification on each run — touches five files because they are all intertwined. In v3, the same feature touches only ingest.py (plus a new notifier.py it imports). The cost difference between v2 and v3 is roughly one feature. By the tenth feature, you are paying the debt on every single change. Teams that defer the structural work because "we're moving fast" are borrowing at a rapidly compounding interest rate.
It is entirely possible to write clean function signatures and docstrings in every module while the import graph is a disaster. Engineers who focus on the API surface of each function — parameters, return types, exceptions — can miss the architectural problem entirely until they run python -c "import tracelab; import sys; print(sys.modules.keys())" and see forty modules loaded for a four-line CLI. Coupling lives in the import graph, not the function signatures. Draw the graph before you defend the architecture.
The most common refactoring mistake when breaking a God module: you extract a new file, but you still have the God module importing the new file and the new file importing the God module. You now have two files and zero improvement. The extraction only helps if you also invert the dependency direction. Every time you create a new module, ask: "does this module know about me?" If yes, you've split the God module in two and replicated its debt.
KEY INSIGHTHow this connects
- 3.10 · TraceLab v2: Client–Server, and the First Race — the God module you just carved apart was the natural result of the Stage 3 server work, where "put it all in one file" was the fastest path. This lesson is the first act of the Stage 4 reckoning.
- 2.1 · Code Is Read 10× More Than It's Written — the readability argument from Stage 2 applies here at the module level: boundaries are the unit at which code is reasoned about, not just read. Cohesive modules with clear dependency direction make the reading 10× faster because you can understand one file without holding all the others in your head.
- 4.2 · Monolith, Services, Serverless: An Honest Accounting → — now that you can draw a clean module boundary within a monolith, the next question is when (and whether) that boundary becomes a network boundary. Spoiler: almost never as soon as you think.
GLOSSARYKey terms introduced
- Afferent coupling (Ca)
- The number of modules outside a module that depend on it — how many modules import this one. High Ca is fine if the module is stable; it means the module is a shared abstraction.
- Efferent coupling (Ce)
- The number of modules a given module depends on — how many things it imports. High Ce for a volatile module means many things can break it.
- Instability (I)
- Ce / (Ca + Ce). A value near 0 means maximally stable (nothing it depends on changes); near 1 means maximally volatile. Stable modules should be abstract; volatile modules should be concrete.
- Cohesion
- The degree to which the elements inside a module belong together for the same purpose. High cohesion: one module, one clearly statable job. The test: can you name the module's purpose without using "and"?
- God module
- A module that knows about everything — high Ce, circular dependencies, low cohesion. Often emerges naturally from "let me just put it here" and is invisible until the third feature request.
- Stable Abstractions Principle (SAP)
- A module's level of abstraction should match its stability. The most stable modules define concepts; the most volatile modules implement details.
- Circular dependency (import cycle)
- A cycle in the module import graph: A imports B, B imports C, C imports A. In Python, this results in partially-initialized module objects and subtle, order-dependent bugs. The fix is always architectural: invert the direction, don't suppress the symptom.
- Dependency inversion
- Making a stable module depend on an abstraction that volatile modules implement, rather than having the stable module import the volatile module directly. Breaks the downward dependency of stable on volatile.
ACTIVE RECALLCheck your understanding
Answer in your own words first, then reveal.
1What do afferent coupling (Ca) and efferent coupling (Ce) measure, and which one predicts how fragile a module is?›
Ca counts how many other modules import this module; Ce counts how many modules this module imports. Ce predicts fragility: a high Ce means many things can break this module when they change. The instability metric I = Ce / (Ca + Ce) captures this: a module with many inputs and no outgoing dependencies (I ≈ 0) is stable because nothing it depends on can change it. A module with many outgoing imports and nothing depending on it (I ≈ 1) is volatile — the leaf of the graph, rightfully so.
2Why are circular imports dangerous in Python beyond just causing ImportError?›
Python's import system memoizes modules in sys.modules while they are being initialized. When a cycle occurs, a partially-initialized module is returned to the importer — meaning the names defined before the cycle-triggering import exist, and the names defined after don't yet. This can "work" at import time (no crash) but give you a module object with missing attributes that silently causes wrong behavior, especially as import order changes during refactoring. The deeper problem is conceptual: a cycle means two modules cannot be understood in isolation — they are logically one component.
3Why should the domain module have Ce = 0 within the system, and what breaks if it imports from storage?›
The domain module defines the core concepts (e.g., Run) that the entire system uses. If it imports from storage (a volatile detail), then any change to the storage layer — switching from CSV to SQLite, changing file encoding, renaming a column — forces a change to the domain module. Because everything depends on domain (Ca is high), that change propagates to every other module. Ce = 0 for domain means the domain concepts are insulated from all implementation details; the system can swap storage, transport, or serialization without touching its vocabulary.
4You extract a God module into two files, but the "cost of change" probe still shows the same number. What went wrong?›
You split without inverting. The new file still imports the old God module, and the old God module still imports the new file — you've created a two-file cycle instead of a one-file God module. The structural problem is unchanged; you've just added a file. The fix requires identifying which module holds the stable concept that both files share, extracting that into a third file that imports nothing internal, and then pointing both original files at it. Extraction without direction inversion is cosmetic, not architectural.