Lesson 0058 · System Architect · Module 3

Map the Domain Model to a Data Model

The domain model decided what facts exist and which must change together. The data model decides how those facts are stored — and the choice is driven by access patterns, not fashion.

Reading ≈ 10 minPractice ≈ 30 min

Mission tie-in: storage is where invariants get their final guard and queries get their shape. Choosing it after the domain, not before, is the sequence this phase teaches.

Knowledge: the model first, storage second

Lesson 0055 found which facts must change atomically. Those clusters are natural units for repository operations and transactions, but they do not require one row, one document, or one physical record: a relational implementation may normalize a cluster across several tables while committing it in one transaction. A return's decision and required evidence may belong to one boundary; the customer's tier does not. References between boundaries use explicit identities rather than object graphs that callers traverse freely.

Separate two decisions that are often mixed together: the data model used for query and update patterns, and the persistence strategy used to retain current state or history:

Use access patterns and required guarantees to choose, not category slogans. A return's decision and evidence have tree-shaped locality, so a document model is credible; reporting across returns and customer tiers favors relational queries. Start with the simplest store that satisfies the important writes, reads, constraints, scale, and team-operability needs. Add a separate read model only when measured query or scale pressure justifies duplicated data and convergence work. Polyglot persistence is an architectural cost, not the default conclusion of having several boundaries.

Whatever the store, the repository (repository, lesson 0013) keeps storage details behind a domain-facing port. The schema is a contract with its own evolution: an expand/contract migration adds the new form, writes both, backfills and verifies, switches reads, then stops old writes. Dropping the old form is a later, deliberately destructive step taken only after a compatibility and retention window; recovery may require backup, restore, or forward repair.

# One cluster persists as one unit; the repository hides the store.
from dataclasses import dataclass


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


@dataclass(frozen=True)
class ReturnRecord:
    return_id: str
    accepted: bool
    refusal: Refusal | None = None


class ReturnStore:
    """Port: load and save one whole cluster. Storage is behind this."""

    def load(self, return_id: str) -> ReturnRecord: ...
    def save(self, record: ReturnRecord) -> None: ...

Worked: splitting one column into a state machine

The transition table from lesson 0054 has to land in storage. Today the legacy table has one status column holding strings; the model needs a state plus a refusal reason plus the transition history. The architect's opening questions were the three that price the change: how many rows, how many writers, and who reads this besides us?

The naive plan — ALTER TABLE, backfill, deploy the new code, drop the old column — fails on two of those four rows, and each failure is instructive. Backfilling 1.9 M rows in one statement holds locks long enough to stall the write path. And the analytics extract, owned by another team on a monthly release, contains SQL that reads status; dropping it breaks a report the finance team sees before anyone on the engineering side notices.

# The mapping is a design decision, written down, not an ORM accident.
from dataclasses import dataclass
from enum import Enum


class State(Enum):
    REQUESTED = "requested"
    APPROVED = "approved"
    REFUSED = "refused"
    REFUNDED = "refunded"


@dataclass(frozen=True)
class ReturnRecord:
    return_id: str
    state: State
    refusal_reason: str | None


# Expand/contract: each step is reversible with a deploy, not a restore.
MIGRATION = [
    ("expand",   "add nullable state and refusal_reason; no default, no rewrite"),
    ("dual",     "write both forms; keep reading the old status column"),
    ("backfill", "5,000 rows per batch, ~380 batches, verified between runs"),
    ("verify",   "comparison query returns zero mismatches on three consecutive runs"),
    ("switch",   "read the new columns behind a flag; old column still written"),
    ("compat",   "publish a status view for the analytics extract, one quarter"),
    ("contract", "stop writing status; drop it after the retention window"),
]


def write_both(row: dict, record: ReturnRecord) -> dict:
    """The dual-write window: one writer, two truths, deliberately."""
    row["state"] = record.state.value
    row["refusal_reason"] = record.refusal_reason
    row["status"] = _legacy_status(record)      # the old contract, still honoured
    return row


def _legacy_status(record: ReturnRecord) -> str:
    return {State.REQUESTED: "pending", State.APPROVED: "approved",
            State.REFUSED: "refused", State.REFUNDED: "refunded"}[record.state]

The batches matter more than they look. At 5,000 rows a batch the backfill is about 380 batches; run with a short pause between them it finishes in roughly half an hour without competing with the portal's traffic, and it can be stopped after any batch. The comparison query is what turns “we think it worked” into evidence: it counts rows where _legacy_status(state) disagrees with status, and the switch does not happen until three consecutive runs return zero.

The one step that is genuinely irreversible is the last. Dropping status cannot be undone with a deploy — only with a restore, and a restore loses everything written since. So it was scheduled eleven weeks after the switch, once the analytics extract had migrated off the compatibility view and the retention window had passed. The alternative — dropping it the same week to “finish the migration” — buys a tidy schema and sells the ability to roll back the whole change.

When this is the wrong move. A new table with zero rows should just be changed — there is nothing to migrate and no reader to protect. A table under ten thousand rows with one writer, no external consumer, and an available window is cheaper to migrate in a single transaction than to choreograph. Purely additive changes with no backfill (a nullable column nobody reads yet) need no dual-write window at all. The sequence in this lesson is priced for a population; when there is no population, skip it and spend the time on something with risk in it.

Skill: choose the shape from the pattern

Practice: map your clusters to storage

Use your consistency boundaries or the supplied returns case. List the important writes, reads, constraints, scale assumptions, and team-operability needs. Compare a relational and document model for the whole system; treat event sourcing as a separate history strategy. Choose the simplest adequate starting point and name the evidence that would justify a second store or read model later. Finally, write an expand/contract sequence including verification, retention window, the destructive step, and recovery if contraction proves premature.

In the lab and the capstone: the companion lab's phase-5 checkpoint stores its state in a shape the domain model has outgrown. Write the mapping you want, then plan the change as an expand/contract sequence and name which step is the irreversible one — that identification is the skill. The worked capstone carries the storage decision in its state and contracts artifact and the reasoning that rejected the alternatives in options and decision records, while the brownfield case walks a larger version of the same migration in expand and contract.

Read and watch deeper

• Designing Data-Intensive Applications, Kleppmann — ch. 3: data models and query languages; ch. 4: encoding and evolution; ch. 5 (2nd ed. ch. 4): schema evolution and compatibility.
• Applying UML and Patterns, Larman — ch. 9–10: mapping the domain model to persistent design (optional; ch. 16: mappings to relational schemas).
• Learning Domain-Driven Design, Khononov — ch. 7 (optional deep-dive: event sourcing as a persistence choice).
• Refactoring Databases: Evolutionary Database Design, Scott Ambler & Pramod Sadalage — the catalogue of schema refactorings with their transition periods, which is expand/contract worked out in detail.
• Related lessons: 0013, 0023; glossary expand/contract, repository.

Ask your agent-teacher to design the schema for your core cluster in all three shapes, then challenge each with your real query list — the weakest shape usually shows itself immediately.