Repositories (DDD)

## What a Repository actually is A **Repository** in Domain-Driven Design is an abstraction that sits between the domain model and whatever technology actually stores data. Concretely, it's an interface — typically declared in the domain (or application) layer — with methods shaped like collection operations: - `add(aggregate)`, `remove(aggregate)`, `findById(id)` - and maybe a small number of purpose-named finder methods such as `findOverdueOrders()` The interface is implemented in the **infrastructure layer**, where the real persistence mechanics live: SQL statements, an ORM session, HTTP calls to a document store, or (in tests) a plain in-memory map. Client code — application services, domain services, other aggregates orchestrating a use case — depends only on the interface, never on the implementation, so it can say `orderRepository.findById(orderId)` and get back a fully-formed `Order` aggregate without knowing or caring how that aggregate was assembled. ## Why it is called a collection illusion The reason this is called a 'collection illusion' traces back to Eric Evans' original description in Domain-Driven Design: a repository should feel, from the caller's perspective, like a conceptual set of all aggregates of that type, already in memory, that you can add to, remove from, and query. That framing matters because it dictates the shape of the interface: - you don't call `orderRepository.executeQuery(sql)`, you call `orderRepository.findById(id)`; - you don't call `save(dto)` with an anemic data bag, you call `add(order)` with a real aggregate carrying its invariants. The illusion pushes the vocabulary of the interface toward the domain and away from the storage technology, which is the entire point — it lets someone read application-service code and understand what is happening (an order is fetched, mutated, and persisted) without being distracted by how persistence works underneath. ## The three problems it solves Why does this exist as a distinct pattern rather than just calling the ORM or database client directly? Three problems it solves: 1. **First**, it decouples the domain model from a specific persistence technology, so swapping Postgres for a document store, or introducing a cache, touches only the repository implementation, not domain or application logic. 2. **Second**, it makes the domain model testable — a domain or application service test can be handed an in-memory fake repository (a `HashMap` behind the same interface) and run with zero database, zero mocking-framework ceremony, and zero I/O latency. 3. **Third**, and most DDD-specific, it enforces the aggregate as the unit of consistency and access: if repositories only ever hand out and accept whole aggregate roots, nothing outside the aggregate can reach in and mutate an internal entity or value object directly, bypassing the invariants the aggregate root is meant to protect. ## The trade-off The trade-off is that the illusion is **never fully free**, and pretending it is causes real damage. A method that looks as cheap as `List<Order> findAll()` may, in a naive implementation, pull an entire table into memory — the collection metaphor **hides cost the same way it hides mechanism**. Query-shaped needs (pagination, filtering, sorting, aggregation, joins across aggregates) don't map cleanly onto `add/remove/findById`, so teams face a real choice: - keep the repository interface narrow and pure (only identity-based access and a few named, intention-revealing finder methods) and push reporting/search needs to a separate read-side, - or widen the repository with more finder methods and risk it slowly becoming a thin wrapper around a query builder — at which point the domain-facing illusion has effectively collapsed back into a data-access object. ## Failure modes Failure modes show up in predictable ways. 1. The most common is leaking the ORM's own entity or session objects out through repository methods instead of returning the domain's own aggregate type — callers end up depending on lazy-loading proxies, and calling a getter outside a transaction throws a lazy-initialization exception because the 'illusion' quietly depended on an open session. 2. Another is exposing something like `IQueryable<Order>` or a raw query-builder from the repository, which hands infrastructure query semantics straight to domain/application code and defeats the whole purpose of the abstraction. 3. A third is having more than one repository type per aggregate (one for `OrderHeader`, another for `OrderLine`), which breaks the aggregate-as-consistency-boundary idea, since callers can now mutate line items without going through the order root. 4. A fourth is repository methods that silently do far more I/O than their name suggests, e.g. a `findById` that triggers N+1 queries to hydrate every child collection eagerly. ## A worked example A concrete worked example: an e-commerce system's `OrderRepository` exposes `findById(OrderId): Order?`, `add(Order): void`, and one named finder, `findUnfulfilledOrdersOlderThan(Instant): List<Order>`, used by a nightly job. The checkout application service calls `findById`, invokes domain methods like `order.applyDiscount(code)` on the returned aggregate, and calls `add` (or `save`) to persist it — it never sees a SQL string, a table name, or an ORM annotation. The infrastructure-layer `JpaOrderRepository` (or a hand-rolled SQL mapper) is the only place that translates the `Order` aggregate to and from rows, and it can be swapped or heavily optimized without a single line in checkout logic changing.