DDD -- Domain-Driven Design

You structure domain code using Evans-style domain-driven design. Follow these rules exactly.

Ubiquitous Language

Every class, method, parameter, and module name must come from the domain language -- the terms the user (domain expert) would use. When you introduce a new domain concept, name it in the language of the problem, not the language of the solution.

• If a name in the code does not map to a concept a domain expert would recognise, rename it.
• If two different concepts share a name, you have a Bounded Context problem (see Strategic Design below).
• A change to the naming is a change to the model. Treat it as such.

Choosing Building Blocks

When introducing a domain concept, classify it using this table:

Default to Value Object. Only use Entity when identity matters independent of attributes. Value Objects are simpler, safer, and easier to test.

Entities

• Define identity with a single, stable, unique identifier. Do not use mutable attributes as identity.
• Implement equality and hashing based on identity only.
• Keep Entities lean -- push attribute-heavy logic into Value Objects owned by the Entity.
• An Entity's primary responsibility is maintaining identity continuity and enforcing invariants on its lifecycle transitions.

Value Objects

• Immutable: no setters, no mutation. All operations return new instances.
• Equality by attributes: two VOs with identical attributes are interchangeable.
• Self-validating: reject invalid state at construction time. A VO that exists is valid.
• Use VOs for: measurements, quantities, ranges, money, dates, addresses, coordinates, descriptions, identifiers (when identity itself is a value -- e.g. ISBN, SSN).
• When an Entity has a cluster of related attributes (e.g., street/city/zip), extract a Value Object.

Domain Services

Use a Domain Service when an operation:

1. Involves multiple Aggregates and does not naturally belong to any one of them.
2. Is expressed as a verb phrase in the Ubiquitous Language (e.g., "transfer funds between accounts").
3. Is stateless -- it depends only on its arguments and injected Repositories/Services.

Do not put domain logic in application Services. Application Services orchestrate (load Aggregate, call domain method, save); domain logic lives in Entities, VOs, and Domain Services.

Aggregates

Aggregates enforce consistency boundaries. These rules are non-negotiable:

Boundary Rules

1. Every Aggregate has exactly one root Entity.
2. External objects may hold references only to the root. Never expose internal objects.
3. Internal objects may hold references to other Aggregate roots.
4. Only the root may be retrieved from a Repository. Internal objects are reached by traversal.
5. Deleting the root deletes everything inside the boundary.

Invariant Rules

6. All invariants within the boundary are enforced on every state change -- the boundary is the transaction boundary.
7. Invariants that span Aggregates use eventual consistency, not transactional consistency.

Sizing Rules

8. Keep Aggregates small. Prefer a single Entity root with Value Objects. Add child Entities only when an invariant demands it.
9. Reference other Aggregates by identity (store the ID), not by direct object reference.

Design Procedure

When defining an Aggregate:

1. Identify the invariants. What rules must always be true?
2. Find the smallest cluster of objects needed to enforce those invariants. That is your boundary.
3. Choose the root -- the Entity that owns the invariants and is the entry point.
4. Everything outside the boundary references the root by identity.

Repositories

• Provide one Repository per Aggregate root. Never for internal objects.
• The interface is pure domain language: find_by_tracking_id(tracking_id), not SELECT * FROM ....
• No query technology leaks into the domain layer -- no SQL, no ORM query builders, no storage-specific types.
• A Repository provides the illusion of an in-memory collection. Methods: add, remove, find_by_*.
• Reconstitution (loading from storage) is distinct from creation (use a Factory for creation of new Aggregates).

Factories

• Use a Factory when constructing an Aggregate requires assembling multiple parts or enforcing invariants that a simple constructor cannot express.
• A Factory method can live on the Aggregate root (for creating related objects), on a standalone Factory, or on another domain object that naturally participates in creation.
• Every object produced by a Factory must satisfy all invariants -- an Aggregate that exists is valid.
• Do not use Factories for reconstitution from storage. Repositories handle that.

Modules

• Name modules from the Ubiquitous Language, not from technical roles. shipping, billing, pricing -- not services, models, utils.
• Low coupling between modules, high cohesion within.
• Module boundaries tell a story about the domain. If you need to explain why two concepts are in the same module, they probably should not be.

Supple Design

Apply these patterns to make domain code easy to use and change:

Intention-Revealing Interfaces

• Name every class and method to state what it does and why, not how. A caller should never need to read the implementation.
• Method name = domain verb phrase. Class name = domain noun.
• If a name requires a comment to explain, rename it.

Side-Effect-Free Functions

• Separate queries (return a result, no side effects) from commands (change state, return nothing).
• Place as much domain logic as possible in functions on Value Objects -- these are naturally side-effect-free.
• When a command is necessary, keep it simple and do not return domain data from it.

Assertions

• State post-conditions and invariants explicitly in docstrings or type contracts.
• Tests should assert invariants, not just outputs. If an Aggregate has a rule "quantity must be positive", test that the rule holds after every operation that touches quantity.

Conceptual Contours

• Decompose along the natural grain of the domain. Elements that change together belong together; elements that change independently should be separate.
• If adding a feature requires modifying many unrelated classes, your contours are wrong.

Standalone Classes

• Reduce dependencies to the minimum. Every dependency is a burden on understanding.
• The ideal: a class that can be understood and tested by reading only its own file plus language primitives.

Closure of Operations

• Where possible, define operations whose argument and return type match the type they are defined on: Money.add(Money) -> Money, Specification.and(Specification) -> Specification.
• Closed operations create composable, self-contained algebras.

Making Implicit Concepts Explicit

When domain logic is buried in conditionals, boolean flags, or string comparisons, a concept is implicit. Surface it:

Strategic Design

Bounded Context

• A model is valid only within its Bounded Context. The same real-world thing may be modelled differently in different contexts.
• When you notice the same term meaning different things in different parts of the codebase, you have discovered a context boundary. Make it explicit.
• Each Bounded Context has its own Ubiquitous Language, its own model, and its own module structure.

Context Map (Solo Dev Adaptation)

Even as a solo developer, map the boundaries between:

• Your domain modules (which may have different models for related concepts).
• External systems you integrate with (APIs, databases, libraries that impose their own model).
• For each boundary, decide the relationship:

Anti-Corruption Layer

When wrapping an external system:

1. Facade: Simplified interface to the external system's API.
2. Adapter: Maps between your calling conventions and the external system's protocol.
3. Translator: Maps between the external system's model and your domain model.

Your domain code calls the ACL. The ACL calls the external system. Domain types never appear in the external system's namespace and vice versa.

Core Domain Vs Generic Subdomain

• Core Domain: the code that makes the application distinctive. If you removed it, the software would be generic. Invest design effort here. Apply supple design. Refactor toward deeper insight.
• Generic Subdomain: necessary but not distinctive (e.g., money, date arithmetic, authentication). Separate into its own module. Use libraries or published models. Do not over-invest in design -- good enough is sufficient.

Decision test: "If I replaced this module with an off-the-shelf equivalent, would the application lose its distinctive value?" If no, it is a Generic Subdomain.

Layered Architecture

Separate domain logic from everything else. Minimal layers for a solo-dev codebase:

The domain layer has zero dependencies on infrastructure, frameworks, or UI. It depends only on language primitives and its own types. Infrastructure implements domain-defined interfaces (dependency inversion).

Refactoring Toward Deeper Insight

• When code is hard to extend, suspect the model first, not the code structure.
• When domain experts describe a concept the code cannot express, add the concept to the model.
• When a name feels wrong, it is wrong. Rename until the code reads like a domain conversation.
• Prioritise refactoring in the Core Domain. A refactoring in the Core has more leverage than one in a Generic Subdomain.