Lesson 0052 · System Architect · Module 1

Build the Domain Model and Its Language

The model is a shared simplification of the domain — and its words are a contract. Discover both from real scenarios before you write a class.

Reading ≈ 10 minPractice ≈ 30 min

Mission tie-in: the glossary of this course works only because every term has one agreed meaning. Your system's vocabulary deserves the same discipline — a shared vocabulary for the domain, precise enough to encode in code.

Knowledge: the model is a tool, not a transcript

In lesson 0051 you found the core subdomain and its experts. Now extract the knowledge: the rules, exceptions, and vocabulary those experts carry. Work from business scenarios — real, concrete cases, including the exceptional ones. A scenario is a story with a beginning, a decision, and an outcome; it is the raw material from which the model is built.

As the stories accumulate, a vocabulary emerges. Capture it as a glossary with one meaning per term, and then encode those words in code: classes, methods, and tests named by the language, not by implementation. When a support agent says "the return was refused," the domain object should have a refusal with reason — not a status == 4.

The model is a simplification, not a transcript of the business. You deliberately leave out what the software does not need — the physical shelf where parcels wait, the phone calls between desks. A model that mirrors every detail is as useless as one that mirrors none; both fail to support thought. What you keep is what matters for the decisions the software must make.

Watch for the words that mean different things to different people. "Approved" may mean policy eligibility to support, inspection passed to the warehouse, and money settled to finance. Each divergence is evidence of a separate model — a future boundary (lesson 0053), not a synonym problem to vote away. The glossary you build here is per-model, not per-company.

Keep the language alive: name classes after it, name tests after it, and write a scenario the way the expert said it. When code and expert disagree, investigate the discrepancy with concrete cases: the code may be stale, the rule may have changed, or two contexts may be using the same word differently.

# Encoded language: the refusal is a decision, not a status number.
from dataclasses import dataclass
from enum import Enum
from datetime import date, timedelta


class Reason(Enum):
    POLICY_WINDOW_PASSED = "policy window passed"
    EVIDENCE_MISSING = "evidence missing"


@dataclass(frozen=True)
class Refusal:
    reason: Reason
    decided_on: date
    decided_by: str


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

    def __post_init__(self) -> None:
        if self.accepted == (self.refusal is not None):
            raise ValueError("a decision must be accepted or refused, exclusively")


def decide(scenario: dict) -> EligibilityDecision:
    """One domain rule, in the language of the policy owner."""
    if scenario["requested_on"] - scenario["purchased_on"] > timedelta(days=30):
        return EligibilityDecision(False, Refusal(
            Reason.POLICY_WINDOW_PASSED, date.today(), "policy engine"))
    return EligibilityDecision(True)

Worked: reading the exceptions, not the nouns

Given a week with the returns experts, a beginner collects nouns: return, customer, order, label. An architect collects refusals, because the exceptions are where a domain hides its rules. The concrete move on this initiative was to pull a sample of 200 refusals from the support tool's free-text notes — one week of manual decisions — and sort them by what the agent actually wrote.

The question the architect asked of every row was the same: is this a rule or a judgement? The 24 VIP entries answered it loudest. They were filed as refusals and then reversed by hand, which means the vocabulary had no word for what actually happened. The expert's own sentence — “except when the customer is VIP, we still accept” — names a policy override, and an override has something a reason code does not: an authority who may issue it and a record of why. Encoding it as a refusal that someone edits afterwards loses both.

The alternative the team rejected was the obvious one: keep reason as free text, because the agents like writing sentences and an enum will always be incomplete. It was rejected for a reason that has nothing to do with tidiness. The initiative's guardrail is a manual review queue of at most 50 cases a day, and you cannot manage what you cannot count: with free text, “how many of last week's manual decisions were already codifiable?” is a data-cleaning project, not a query. The compromise they shipped keeps both — a required reason code and an optional note — with the unclassified bucket as the backlog the policy owner works down.

# The vocabulary, encoded: a refusal carries its cause, an override its authority.
from dataclasses import dataclass
from enum import Enum


class Reason(Enum):
    POLICY_WINDOW_PASSED = "policy window passed"
    EVIDENCE_MISSING = "evidence missing"
    CONDITION_DISPUTED = "condition disputed"     # the judgement bucket
    UNCLASSIFIED = "unclassified"                 # the backlog, counted honestly


@dataclass(frozen=True)
class PolicyOverride:
    """“Except when the customer is VIP, we still accept.” — the policy owner."""

    granted_by: str          # an authority, not a checkbox
    justification: str


def codifiable_share(refusals: list[Reason]) -> float:
    """The number the policy owner asks for every month."""
    codified = sum(1 for r in refusals
                   if r not in (Reason.CONDITION_DISPUTED, Reason.UNCLASSIFIED))
    return codified / len(refusals)


SAMPLE = ([Reason.POLICY_WINDOW_PASSED] * 61 + [Reason.EVIDENCE_MISSING] * 44
          + [Reason.CONDITION_DISPUTED] * 31 + [Reason.UNCLASSIFIED] * 40)
assert round(codifiable_share(SAMPLE), 2) == 0.6   # 105 of the 176 real refusals

A year later that enum is what makes a policy question answerable in an afternoon: “how many refusals would flip if we moved the window from 30 days to 45?” is a filter over one column. The same question against free text is a week of somebody reading. The vocabulary you choose is the query surface you will have.

When this is the wrong move. Do not build a model and a vocabulary for work that owns no decisions. In an integration or reporting job, the source system's vocabulary is the domain language; inventing your own adds a translation layer with nothing on the far side of it. In a genuinely generic subdomain, speak the vendor's language inside the adapter — a carrier calls it a “consignment”, and renaming it to please your model just makes their support tickets harder to read. And in a throwaway experiment, the scenarios are worth gathering but the glossary is not worth maintaining; write down what you learned and delete the code.

Skill: hear the model in the stories

Practice: extract the language from three stories

Take a core subdomain you mapped in lesson 0051. Use three real scenarios from an expert, or use the three returns statements in the worked table above as your supplied case. For each: preserve the speaker's words, extract the nouns and verbs, and build a small glossary with one precise meaning per term. Mark words that could mean different things in another context. Then encode two important rules as named domain functions and write one counterexample for each.

In the lab and the capstone: the companion lab's phase-5 checkpoint gives you a returns-resolution service whose names came from the database rather than from anyone who does the work. Before restructuring it, write the glossary the code implies, then the glossary the scenarios imply, and mark every place they disagree — those marks are your refactoring list. The worked capstone carries the same vocabulary through its workflow and drivers artifacts, so you can see which words survived all the way to a decision.

Read and watch deeper

• Applying UML and Patterns, Craig Larman — ch. 9: domain models — concepts, relationships, and terminology before database or classes exist.
• Learning Domain-Driven Design, Vlad Khononov — ch. 2: discovering domain knowledge and building the vocabulary (optional deep-dive).
• Domain-Driven Design, Eric Evans — ch. 2: a shared language as a living, enforced contract; ch. 3 on binding the model to the implementation so the words cannot drift.
• Specification by Example, Gojko Adzic — ch. 6–8: deriving shared vocabulary from concrete business examples and keeping it executable.
• Related lesson: 0041 shows the workflow-mapping side of the same discovery; glossary · domain modeling.

Give your agent-teacher the anonymized scenario transcript and ask it to draft the glossary — then treat every term it invents as unverified until the expert confirms or corrects it.