Lesson 0013 · Core Designer · Module 3

Repository Boundaries That Don't Leak

A repository is a collection, from the domain's point of view. When it starts showing its storage internals, the domain stops being protected.

Reading ≈ 9 minPractice ≈ 30 min

Mission tie-in: the repository is the port from lessons 0009 and 0010, specialized for storage. It's also the boundary your AI prompts should name explicitly.

Knowledge: a collection, not a query API

The repository's job: let the domain load and save aggregates as if they lived in a collection. The domain never learns about SQL, sessions, or ORMs. The port speaks domain language:

class OrderRepository(Protocol):
    def get(self, order_id: str) -> Order: ...
    def add(self, order: Order) -> None: ...
    def delete(self, order_id: str) -> None: ...


class SqlAlchemyOrderRepository:
    def __init__(self, session: Session) -> None:
        self._session = session

    def get(self, order_id: str) -> Order:
        row = self._session.execute(
            select(OrderRow).where(OrderRow.id == order_id)
        ).scalar_one()
        return Order(...)                # row -> domain aggregate

    def add(self, order: Order) -> None:
        self._session.add(OrderRow.from_domain(order))

The boundary's proof is the fake — a drop-in replacement with no storage at all:

class InMemoryOrderRepository:               # implements the same port
    def __init__(self) -> None:
        self._orders: dict[str, Order] = {}

    def get(self, order_id: str) -> Order:
        try:
            return self._orders[order_id]
        except KeyError:
            raise OrderNotFound(order_id)    # the port's vocabulary, not the ORM's

    def add(self, order: Order) -> None:
        self._orders[order.order_id] = order

Twelve lines, no database, and every domain test runs against it in milliseconds. That is also the diagnostic: if your fake cannot be written in a dozen lines, the port is carrying storage semantics it should not — lazy loading, session lifetimes, flush ordering. Note the error too: the fake raises OrderNotFound, not KeyError and not the ORM's NoResultFound. The port owns its failure vocabulary as much as its methods.

What makes this boundary honest is what it refuses:

• No session, query, or ORM types appear in the port or in domain callers.
• Queries are expressed as domain questions: get_unshipped(), not filter(status=...) with raw column names.
• The domain gets domain objects back — never rows, dicts, or ORM models.
• Persistence details — transactions, lazy loading, caching — live behind the boundary.

Test it the lesson-0009 way: a fake in-memory repository must be a drop-in, and the domain must never know which one it holds. If your fake has to mimic ORM behavior, the boundary leaked.

How a senior designer works the case

An order service: eight engineers, twenty-five endpoints, a repository boundary everyone is proud of. After one sprint, the order-list page's p95 goes from 180 ms to 1.4 s. The ticket says "the repository is slow."

What they look at first. Not the SQL, and not the adapter. The call site, next to the port's signature:

# the port looks immaculate
class OrderRepository(Protocol):
    def get(self, order_id: str) -> Order: ...

# the caller wrote the loop the port invited
def order_list(order_ids: list[str], repo: OrderRepository) -> list[OrderSummary]:
    return [summarize(repo.get(oid)) for oid in order_ids]   # 50 round trips

The question they ask. "Which side of this boundary decides how many round trips happen?" Here, neither did on purpose: the caller wrote an innocent comprehension, the port had no way to express "fifty at once", and the fake — which returns from a dict — made the loop look free in every test. That is the diagnosis. The port hid cost, and the fake made the hiding invisible.

The alternatives they reject. The quick fix is get_many(ids), then get_with_lines(ids) for the next screen, then get_with_lines_and_shipping(ids). Each is reasonable alone; together they grow one method per screen, so a write-model interface slowly becomes a read API with nineteen methods, six of them used once, all of which the fake and every implementation must support forever. The other tempting fix — switching the ORM to eager loading globally — repairs this page and pessimizes every write path, and makes the port's behaviour depend on a configuration line in a different file.

What they choose, and what it costs. Split the two jobs the boundary was doing. The repository stays narrow and aggregate-shaped for the write side: load one thing by identity, change it, save it. A separate read side — a query service — is allowed to know SQL, because reading is a query:

@dataclass(frozen=True)
class OrderSummary:                # a read model, not a domain aggregate
    order_id: str
    customer_name: str
    line_count: int
    total_cents: int

class OrderQueries(Protocol):      # a separate port, read-only
    def recent_summaries(self, limit: int) -> list[OrderSummary]: ...

The consequence over time. Two boundaries with different rules is more code than one, and the honest cost is a second mapping path that can drift from the first. What it buys is that neither side has to lie: the domain keeps its twelve-line fake and its microsecond tests, the list page gets one statement instead of fifty, and the next screen adds a read model instead of another method to an interface eleven classes implement. The failure mode you avoid is the one that kills repositories in practice — a port that grows until nobody can implement it and everybody routes around it.

When this is the wrong move

• Reporting, search and analytics. Go to the engine directly, with a read model. A repository between a dashboard and a warehouse query buys nothing and costs expressiveness.
• Set-based work. "Expire the 40,000 sessions older than a day" is one statement in SQL and a disaster as a loop over a collection. Put it behind a named domain operation, and let the adapter do it in one round trip.
• Small applications where the ORM model is the model. One team, one storage, CRUD rules, no plans to swap: the port is ceremony, and the honest design is to admit the framework is the architecture. Say so in an ADR so the next person knows it was a decision.
• Spikes. A boundary you introduce before you know the domain's questions will be a boundary shaped by your first guess. Write the ugly version, learn the queries, then draw the line.

Skill: what crosses the boundary?

Practice on your own code

Look at how your code fetches and saves domain objects. Grep the domain folder for your ORM's import. If it appears — or if the boundary doesn't exist yet — introduce a repository port with domain-named methods and move the ORM behind it.

In the lab: the phase-1 checkpoint has a returns store that hands ORM rows and a live session back to the service layer, and a list endpoint that loops one lookup per return. You give the port a domain vocabulary, write the in-memory fake, and decide which of the remaining calls belongs on a read side instead.

Read and watch deeper

• Architecture Patterns with Python, Percival & Gregory — ch. 2 "The Repository Pattern": the clearest working treatment, with the fake-repository test.
• Implementing Domain-Driven Design, Vernon — ch. 12 "Repositories": design rules for repository interfaces.
• Domain-Driven Design, Evans — ch. 6: the original repository concept, and why it exists.
• Patterns of Enterprise Application Architecture, Fowler — the Repository entry in the object-relational metadata mapping patterns: the original catalog definition, and the Query Object it is usually paired with.
• Fowler, "CQRS" — the argument for letting the read side and the write side have different models, with an explicit warning about when the split is not worth it.
• Watch: ArjanCodes YouTube — search "repository pattern".
• Reference: Patterns — Repository and Unit of work, the transaction boundary the repository sits inside.

Show your agent-teacher your data-access code and audit the boundary together — grep included.