Lesson 0056 · System Architect · Module 2

Carve Components as Deep Modules

The boundary map says where components live. Depth says how good each component is: a small interface hiding a powerful implementation — not a thin layer over someone else's work.

Reading ≈ 10 minPractice ≈ 25 min

Mission tie-in: components are where every earlier decision — responsibilities, boundaries, state machines, invariants — becomes code. Depth is the quality bar for that translation.

Knowledge: interface small, implementation powerful

A deep module has a small interface and a powerful implementation: callers see a handful of meaningful operations, and the module hides substantial complexity behind them. A shallow module is the opposite — an interface nearly as complex as its implementation, or worse, one that merely forwards: it adds a name but no leverage (glossary: information hiding).

Compare two shapes for the eligibility context:

Four Ousterhout moves make modules deep:

• Hide what can change. The policy's internal rule structure, the evidence store's layout, the vendor's quirks — all behind one interface. A caller that touches any of them is coupled to a change you want to make freely.
• Pull complexity downward. When a caller needs a helper to use your module correctly, the module is too shallow: move the orchestration in. The module should make the common case simple and the complex cases contained.
• Make the interface general enough, the implementation specific. Avoid mirroring one caller's incidental steps, but do not invent extension points for hypothetical uses. An operation like assess(return_) expresses the durable domain capability without exposing today's orchestration.
• Different layers, different abstractions. A layer that only forwards calls to the layer below is decoration. Each layer must add meaning — translation, policy, or state — or it should not exist.

Then comes the assembly question: better together or better apart? Ousterhout's test is about change, not resemblance. Two things belong together when they change together and are used together; they belong apart when one can change without the other. The eligibility policy and its assess() guard live together; the eligibility module and the label printer change on different beats — apart, behind contracts.

Depth also pays for itself at the system level: a deep module has fewer seams to enforce, fewer contracts to version (lesson 0057), and more room to change internally without a ripple. When lesson 0059 weighs extracting a service, the extraction is only viable if the seam is already this deep.

# Deep: one call, powerful implementation. Callers never see the rules.
from dataclasses import dataclass
from datetime import timedelta


@dataclass(frozen=True)
class EligibilityDecision:
    accepted: bool
    refusal: str | None = None


class EligibilityService:
    """Hides the policy window, the evidence rules, and the override table."""

    def __init__(self, policy_repo, override_table, clock):
        self._policy = policy_repo
        self._overrides = override_table
        self._clock = clock

    def assess(self, return_) -> EligibilityDecision:
        if self._overrides.is_vip(return_.customer):
            return EligibilityDecision(True)
        if self._clock.today() - return_.purchased_on > timedelta(
            days=self._policy.window_days()
        ):
            return EligibilityDecision(False, "policy window passed")
        if not self._policy.evidence_satisfied(return_.evidence):
            return EligibilityDecision(False, "evidence incomplete")
        return EligibilityDecision(True)

Worked: the interface that leaked a rule

The way to judge a module is to read its callers, not its code. On the existing returns tooling, the eligibility module had eleven call sites. Six of them replicated the same five-step sequence: load the policy, check the window, check the evidence, check the VIP override table, then persist the decision. That duplication is not a style problem — it is the module telling you it never absorbed the orchestration.

Two of the six had dropped the VIP check. Not maliciously: they were written a year apart from the other four, by people copying whichever call site was nearest. Both sat on the support tool's path, which is exactly the path a VIP customer's escalated case travels. Twenty-four VIP returns were refused in the first month of the pilot before anyone connected the complaints to the code.

# Shallow: the module exposes steps, so every caller re-implements the policy.
def handle_return_request_shallow(eligibility, return_):
    policy = eligibility.get_policy(return_.category)
    if not eligibility.check_window(return_, policy):
        return eligibility.save_decision(return_, accepted=False,
                                         reason="policy window passed")
    if not eligibility.check_evidence(return_, policy):
        return eligibility.save_decision(return_, accepted=False,
                                         reason="evidence incomplete")
    # The line two of six call sites never had:
    #     if eligibility.check_vip(return_.customer): accept anyway
    return eligibility.save_decision(return_, accepted=True, reason=None)


# Deep: one call. The rule cannot be forgotten because it is not exposed.
def handle_return_request_deep(eligibility, return_):
    return eligibility.assess(return_)

The question the architect asked at the review was the diagnostic one: what does every caller have to know that it should not? The answer named the interface exactly — the order of the checks, the existence of an override table, and the fact that a refusal must carry a reason. All three are policy, and policy belongs inside the module that owns the policy.

The alternative the team proposed first was an EligibilityFacade wrapping the existing seven methods, leaving both available so nothing had to be migrated at once. It was rejected on a specific ground rather than a purist one: two doors into the same state means the rules can still be bypassed, so the incident stays possible while the code grows a layer that only forwards. What shipped instead was assess() as the single public entry, the seven methods made private, and an import rule in the build (lesson 0059) that fails if anything outside the module reaches past it. Migration took two days because there were only eleven call sites; deferring it would have meant migrating whatever the number had grown to.

The payoff arrived fourteen months later, when the policy moved out of a YAML file into a table with an editing UI for the policy owner. That change touched one module and zero callers. Under the shallow shape it would have touched eleven call sites in three modules, each needing its own review, and at least one would have been missed — the same way the VIP check was.

When this is the wrong move. A general-purpose mechanism library is meant to be wide: hiding a numeric routine behind one “do the right thing” call makes it useless for the caller who needed the other thing. When a single caller genuinely needs three orchestration variants and folding them in produces assess(return_, strict=False, skip_evidence=True, audit=False), the depth is fake — the complexity moved into flags. Split into two honest modules, or expose a small explicit sequence and document why. And do not deepen a module whose shape you do not yet know: an interface invented for hypothetical callers is speculative generality (lesson 0028), and it will be wrong in a way that is expensive to unwind.

Skill: judge a component's depth

Practice: deepen one component

Take the most important component in your boundary map, or use the supplied eligibility component. Write its current interface. Mark every caller that must know an internal detail — a call order, policy rule, vendor type, or config knob. Redesign toward a small set of capability-level operations, hiding those details; “five or fewer” is a prompt, not a rule. Finally, list what changes together inside it and what changes separately, and decide whether anything should move across the seam.

In the lab and the capstone: the companion lab's phase-5 checkpoint gives you components whose callers do most of the work. Count the call sites of the riskiest one, list what each of them has to know, and deepen the interface until that list is empty — then check whether any caller behaves differently from its neighbours, because that difference is usually a bug rather than a requirement. The worked capstone shows the resulting component shape in its architecture views.

Read and watch deeper

• A Philosophy of Software Design, John Ousterhout — ch. 4–9: deep modules, information hiding, general-purpose modules, layers, pulling complexity downward, better together or apart. This phase's component source.
• “On the Criteria To Be Used in Decomposing Systems into Modules”, David Parnas, Communications of the ACM 15(12), December 1972 — the original argument that modules should hide decisions likely to change, not steps in a process.
• Related lessons: 0006 for the change test, 0022 for enforcing the seams; glossary deep module, design principles · deep modules.

Give your agent-teacher one of your component interfaces and ask it to call the module the way a naïve consumer would — every question it asks reveals a hidden complexity that belongs inside.