supple-design

Supple Design

A reference for Eric Evans' supple design patterns as described in Domain-Driven Design (Ch. 10). Supple design is the style that makes a deep domain model usable — code that reads like the ubiquitous language, composes cleanly, and makes changes safe.

Supple design is not a universal requirement. It has a real cost in up-front modeling effort. Evans is explicit: invest in supple design where deep model insight pays off — the Core Domain, and the hot spots that domain experts keep returning to. Generic CRUD, admin tooling, configuration objects, and thin infrastructure wrappers are usually fine without it.

This document defines the eight patterns, each with the same structure:

• Intent — what the pattern establishes, in one or two sentences.
• Signals — concrete things to look for in code when assessing whether the pattern is absent.
• Not a violation when — conditions under which the apparent signal is benign.
• Remediation sketch — what a good application of the pattern looks like.
• Interactions — how the pattern reinforces or depends on neighbors.

Ruby/Rails idioms appear inline as illustrative examples. The patterns themselves are language-agnostic; the Ruby notes sharpen detection in the ecosystem this reference is most often used against.

---

1. Intention-Revealing Interfaces

Intent. Name classes, methods, and arguments so a reader can use them with confidence without opening the implementation. The name should reveal the effect and the purpose — the what and the why — not the how. When a method's name captures the business concept exactly, it disappears into the ubiquitous language.

Signals.

• Generic verbs on domain methods: process, handle, manage, execute, do*, perform, run.
• Suffixes that replace the domain concept: *Util, *Helper, *Manager, *Processor, or an overly broad *Service attached to a domain object.
• Names describing mechanism rather than purpose: calculate, compute, update, set*, insertOrUpdate, doTransaction.
• Method whose body does more than its name implies (a getTotal that also persists, a validate that also sends email).
• Parameter names like arg, data, obj, params, options on domain APIs.
• Doc comments that explain the name rather than the contract (a comment that says "This actually also does X" is a name failure).

Not a violation when. The class is infrastructure (a serializer, a connection pool, a generic collection) or a technical utility. Generic names are correct when the concept is generic.

Remediation sketch. Rename toward the domain. OrderManager.process(order) becomes Order#place, Order#fulfill, Order#cancel — each a distinct concept in the language. Split methods whose behavior exceeds their name.

Interactions. Intention-Revealing Interfaces are a prerequisite for Declarative Design — declarative code reads as a composition of intentions, which only works if each name is a faithful intention. They also depend on Side-Effect-Free Functions, because a name that hides a side effect is not actually revealing.

---

2. Side-Effect-Free Functions

Intent. Separate commands (operations that change state) from queries (operations that compute and return a value without observable side effects), and push as much logic as possible into the query side. Side-effect-free functions can be composed, re-evaluated, tested, and reasoned about locally. Commands remain small, explicit, and well-marked.

Signals.

• Methods that both mutate and return a meaningful value (CQS violation): order.addItem(i) that returns the new total; cart.apply(coupon) that mutates cart and returns the discount.
• Domain operations implemented as chains of void setters invoked by an application service that assembles the result.
• Value objects with setters at all (a value object should be immutable; operations should return new instances).
• Query methods that write to logs at domain-object level, mutate caches on the entity, lazy-load by mutating the object graph, or record audit trail entries as a side effect.
• "Getters" that compute on the fly but mutate fields to cache the result (self-modifying queries).

Not a violation when. The side effect is the point — a well-named command (Order#place, Account#withdraw) can return a result (a Receipt, a Transaction) as long as the name makes the side effect explicit. The CQS rule is strong, but a returning command named for the command is not hidden.

Remediation sketch. Lift computation into a pure function on an immutable value object. Have commands delegate to a pure function to compute the new state, then perform the single, well-named mutation. Favor returning new instances over mutating.

Interactions. Enables Closure of Operations (pure ops compose; mutating ops do not). Enables Assertions (preconditions/postconditions are clean on functions). Required for Declarative Design.

---

3. Assertions

Intent. State the post-conditions of operations and the invariants of aggregates explicitly, so behavior is characterized independently of implementation. Assertions make the model's rules visible at the point where they must hold.

Signals.

• Entity constructors and setters with no guard clauses; invalid states constructible.
• Aggregate invariants enforced only at the database layer (NOT NULL, CHECK, unique constraints) or only in application services, not on the domain object itself.
• Validation duplicated across controllers, services, and UI — no single place where the rule lives.
• Tests that describe what the method does (white-box), not what it guarantees (black-box) — a sign that the contract is not stated.
• Comments in domain code explaining "this must never be null" or "only call after X" — the contract is informal and therefore unreliable.

Not a violation when. The type system already encodes the invariant (a non-null typed parameter in a strict language; an enum with exhaustive cases). Trust the type.

Remediation sketch. Move invariants onto the domain object itself — constructor validation, guarded setters (or better, no setters), explicit ensure/assert/guarded methods. Replace primitive obsession with value objects whose constructors enforce validity; an instance's existence is then proof of its validity. In Ruby, Email = Data.define(:value) do ... end with a validating constructor. Promoting each key of a hash-shaped concept to a named attribute is itself the act of stating the contract — the hash has no preconditions, the value object does.

Interactions. Assertions are how you know Side-Effect-Free Functions and Intention-Revealing Interfaces are honest. They give Specification its teeth.

---

4. Conceptual Contours

Intent. Decompose along the natural fault lines of the domain, so cohesive concepts stay together and changes ripple through as few places as possible. The structure of the code should match the structure of the concepts, at whatever granularity is stable.

Signals.

• Shotgun surgery: one domain change requires edits in many scattered files. Check recent commits — files that change together but live apart are a signal.
• A class with unrelated responsibilities because the author followed a layering or framework convention rather than the domain (e.g., a UserService that validates emails, computes tax residency, issues refunds, and sends notifications).
• Domain concepts that are split across classes because of technical plumbing — persistence, serialization, transport — rather than because the split reflects a real domain distinction.
• Classes named after layer or role (*Controller, *Service, *Helper) holding logic that belongs together on a domain object.
• Two classes with near-identical change histories — candidates for merging, or for extracting a shared concept they both depend on.

Not a violation when. The split is the conceptual contour — e.g., Order vs. OrderLine is a real domain distinction, even though they change together. The test is: does a domain expert recognize the split as meaningful, or does it feel like a plumbing artifact?

Remediation sketch. Merge or reshape until a single domain change can be made in a single place. Where a concept is distributed, name and extract it. Let the ubiquitous language drive the seams.

Interactions. Good contours make Standalone Classes possible (fewer cross-contour dependencies) and make Intention-Revealing Interfaces easier to name (the concept is already distilled).

---

5. Standalone Classes

Intent. Reduce a class's dependencies to the bare minimum so it can be understood in isolation. A standalone class makes no reference to other domain types beyond what is essential to its concept. Low implicit coupling means low cognitive load.

Signals.

• Deep import chains in the domain model layer: a small class pulling in large portions of the rest of the model.
• Value objects that reference entities, or worse, aggregates — usually a sign of a leaky boundary.
• Helpers, utilities, or mixins that drag in transitive dependencies across the domain.
• Repeated raw access to an implicit data shape across classes (obj["type"], dict["labels"], h[:name]) where the shape is a domain concept waiting to be named — a missing value object. Three or more call sites indexing by the same string keys is a strong signal.
• A class whose test requires building a large object graph to exercise a simple behavior (high setup cost as a proxy for high coupling).
• Domain classes that import infrastructure types (DB session, HTTP client, logger, serializer).

Not a violation when. Aggregates need roots to reference their members; entities reference value objects. These are essential domain connections, not coupling for convenience.

Remediation sketch. Lift behaviors onto the concept they most belong to. Replace dependencies with primitives or value objects where possible — Data.define in Ruby (≥ 3.2), @dataclass(frozen=True) in Python, data class in Kotlin, case class in Scala are the idiomatic immutable value-object shapes. Pass in only the data the operation needs, not the whole graph. Push infrastructure out of the model layer.

When two concrete value objects share most of their behavior, the first reach is a module/mixin with two implementations, not an abstract base class with subclasses. Inheritance is a deliberate later choice when the hierarchy itself carries domain meaning (a true Liskov-substitutable relationship). In Ruby, that looks like:

module Field
  def mirror_expectations = raise NotImplementedError
end

ScoreField = Data.define(:name, :scale) do
  include Field
  def mirror_expectations = { scale: scale }
end

TextField = Data.define(:name, :labels) do
  include Field
  def mirror_expectations = { labels: labels }
end

The module states the contract; each Data.define class promotes previously implicit hash keys (scale, labels) to explicit attributes.

Interactions. Standalone Classes are what Conceptual Contours produce when the contours are clean. They are reinforced by Closure of Operations (operations closed over a type don't import others).

---

6. Closure of Operations

Intent. Where it fits the domain, define operations whose argument and return types are the same — an operation closed over a type. Closure yields an algebra: operations compose without leaving the type, which is how you get fluent, expressive domain code.

Signals.

• Value-object operations that return a primitive or a foreign type instead of Self. Money.add(Money) returning BigDecimal. DateRange.extend(Duration) returning a tuple. Path.append(String) returning String.
• Static helpers that take two of a type and return a third — good candidates to promote to methods that close over the type.
• Builder patterns where the same operation naturally composes if expressed as T.op(T) -> T — e.g. merging filters, unioning sets, combining price adjustments.
• Repeated manual unwrapping/rewrapping at call sites — a sign the type escaped when it shouldn't have.

Not a violation when. The operation genuinely crosses types (a Customer ordering a Product yields an Order — three different concepts). Don't force closure.

Remediation sketch. Return Self from value-object operations. If an operation's arguments include a foreign type, look for a specialized closed operation it can be expressed in terms of (e.g., Money.scale(factor) closed over Money, rather than Money * BigDecimal -> Money). In Ruby, Money = Data.define(:amount, :currency) do def +(other); ...; end end is the natural shape — Data.define gives structural equality and immutability for free, so closed operations compose without the usual ceremony.

Interactions. Closure depends on Side-Effect-Free Functions (you cannot compose mutating operations without tears) and is what Standalone Classes feel like in the value-object layer.

---

7. Declarative Design

Intent. Describe what is true in the domain, rather than the procedure for computing it. Declarative domain code often takes the form of a small internal DSL, a combinator library, or a Specification-based query/validation layer. The reader sees intent; the machinery sits underneath.

Signals.

• Business rules expressed as imperative procedures in services — long methods that validate, filter, transform, and branch, where the rule is buried in the control flow.
• Duplicated boolean predicates across places — the same "is eligible" check inlined in three services and two views.
• Validation logic spread across controllers, service objects, and form layers — no place where the rule is the rule.
• Hand-rolled filtering/selection at the repository layer for domain predicates (repeatedly passing the same conditions to a query builder).
• Configuration that says how (imperative steps, ordered arrays) rather than what (declarative facts).

Not a violation when. The logic is genuinely sequential and stateful (a checkout workflow with external side effects at each step; a saga). Forcing declarativity on inherently procedural behavior obscures rather than reveals.

Remediation sketch. Introduce a Specification (see §8) or small combinator API to name the predicate. Replace duplicated checks with references to the spec. Where the rule is complex, a small internal DSL — even a few chainable factory methods — often reads like the ubiquitous language.

Interactions. Declarative Design is the payoff of Intention-Revealing Interfaces, Side-Effect-Free Functions, and Closure of Operations put together. Specification is its most common incarnation.

---

8. Specification

Intent. Encapsulate a predicate — a question you can ask of a domain object — as a first-class object. Specifications can be composed (and, or, not), reused for validation, selection, and construction, and moved between layers without losing meaning.

Signals.

• The same boolean predicate inlined at multiple call sites: order.total > 100 && !order.customer.vip && order.items.any { it.digital } in three services.
• Repository methods accumulating arguments to express selection logic (findOrders(minTotal, excludeVip, digitalOnly, ...)) — the predicate wants to be an object.
• Validation rules re-implemented per layer: one in the form, one in the service, one in the database constraint.
• Factory methods that branch on domain predicates to decide how to construct — the predicate is a Specification in disguise.
• Test fixtures that describe "an order that is eligible for X" procedurally instead of by reference to a named rule.

Not a violation when. The predicate is one-off, narrow, and unlikely to be reused. Do not introduce a Specification for a single caller — introduce it when the duplication appears or when the rule has a name in the ubiquitous language.

Remediation sketch. Extract the predicate as XSpecification with an isSatisfiedBy(candidate) method. Compose via and, or, not. Use the same spec for validation (assert on entry), selection (translate to a query predicate in the repository), and construction (guide factories). Name the spec after the business concept.

Interactions. Specification is the classic vehicle for Declarative Design in DDD. It depends on Intention-Revealing Interfaces (the spec name is a concept in the language) and Side-Effect-Free Functions (a predicate with side effects is a category error).

---

Applying these patterns

When reviewing code with this reference loaded, keep these cross-cutting rules in mind:

• Target the Core Domain and hot spots. Supple design has a cost. It is worth it where deep insight accrues. It is usually not worth it for generic CRUD, admin tooling, or thin adapters.
• Read the body, not just the name. A well-named method can still hide side effects; a badly-named method can be correct. Confirm by reading.
• Don't flag everything. A review with 5 well-grounded findings on central classes is more useful than one with 30 stylistic nits.
• Ground every finding in a pattern. If you can't name which pattern a smell violates and why, the smell probably belongs to a different review (modularity, tactical patterns, ubiquitous language).
• Stay in the domain layer. App/infra code is usually supposed to be procedural and side-effectful. Don't flag a controller for not being side-effect-free.
• Match the idiom of the host language. A Ruby remediation is Data.define, not class Foo; attr_reader; def initialize…. Python: @dataclass(frozen=True). Kotlin: data class. Scala: case class. When two concrete types share most behavior, reach first for a module/mixin with two implementations; reach for inheritance only when the hierarchy itself carries domain meaning.