Context as Code
Documentation

Domain-Driven Design

DDD philosophy: domain at the centre, ubiquitous language, bounded contexts, aggregates, and tactical design building blocks.

Status: Extracted
Purpose: Core Domain-Driven Design (DDD) philosophy and principles for structuring software around business domains.

Overview

This document establishes the fundamental Domain-Driven Design approach for building software that reflects business reality. DDD is a methodology for developing complex software by connecting implementation to an evolving model of the core business concepts.

Key Principle: Software should be structured around the business domain, not technical concerns. The domain model drives architecture, not the reverse.

Core Philosophy

Domain at the Center

Principle: Business logic and domain concepts are the heart of the software. Technical concerns (databases, APIs, frameworks) are secondary.

Rationale:

  • Software exists to solve business problems
  • Domain logic is the most valuable and complex part
  • Technical concerns change, domain concepts are more stable
  • Domain expertise is critical for building correct software

Application:

  • Start with understanding the domain
  • Structure code around domain concepts
  • Domain layer is independent of technical infrastructure
  • Domain experts collaborate with developers

Anti-Pattern:

  • ❌ Structuring code around database tables
  • ❌ Letting frameworks drive domain structure
  • ❌ Technical concerns dictating domain boundaries

Ubiquitous Language

Principle: Use the same language for domain concepts in code, documentation, and conversations with domain experts.

Rationale:

  • Reduces translation errors between domain experts and developers
  • Code becomes self-documenting
  • Domain concepts are clearly expressed
  • Communication is more effective

Application:

  • Use domain terms in code (class names, method names)
  • Use domain terms in documentation
  • Use domain terms in conversations
  • Avoid technical jargon when domain terms exist

Example:

  • ✅ Use "Account" (domain term) not "UserRecord" (technical term)
  • ✅ Use "Conversation" (domain term) not "ChatSession" (technical term)
  • ✅ Use "Enrollment" (domain term) not "Registration" (generic term)

Anti-Pattern:

  • ❌ Technical terms in domain code
  • ❌ Different terms for same concept in code vs. documentation
  • ❌ Generic terms instead of domain-specific terms

Bounded Contexts

Definition

Bounded Context: A boundary within which a particular domain model is valid and applicable. Each bounded context has its own ubiquitous language, domain model, and business rules.

Key Characteristics:

  • Own Domain Model: Entities, aggregates, value objects specific to this context
  • Own Ubiquitous Language: Consistent terminology within the context
  • Own Business Rules: Invariants and constraints specific to this context
  • Clear Boundaries: What belongs inside vs. outside the context

Why Bounded Contexts Matter

Problem: A single domain model for an entire system becomes too complex and contradictory.

Solution: Divide the system into bounded contexts, each with its own model.

Benefits:

  • Clear boundaries and responsibilities
  • Models stay focused and manageable
  • Different contexts can use different terms for similar concepts
  • Teams can work independently on different contexts

Example:

  • Account Context: "Account" means user account with authentication
  • Billing Context: "Account" means billing account with payment methods
  • Same word, different meaning in different contexts

Domain Modeling

Domain Discovery First

Principle: Never propose a domain model without first understanding the domain through discovery.

Process:

  1. Talk to Domain Experts: Understand the business, not just requirements
  2. Identify Core Concepts: What are the fundamental domain concepts?
  3. Understand Relationships: How do domain concepts relate?
  4. Identify Business Rules: What invariants must always be true?
  5. Model the Domain: Only then create the domain model

Rationale:

  • Assumptions lead to incorrect models
  • Domain experts know the business best
  • Discovery reveals hidden complexity
  • Correct model reflects business reality

Anti-Pattern:

  • ❌ Creating domain model from assumptions
  • ❌ Skipping domain discovery
  • ❌ Technical model instead of domain model

Domain Model Elements

Entities:

  • Objects with identity (have IDs)
  • Can change over time
  • Compared by identity, not attributes

Value Objects:

  • Immutable objects defined by their attributes
  • No identity (no ID)
  • Compared by attributes, not identity
  • Can be replaced, not modified

Aggregates:

  • Clusters of entities and value objects
  • Single aggregate root controls access
  • Consistency boundary for business rules
  • Clear boundaries (inside vs. outside)

Domain Services:

  • Operations that don't belong to a single entity
  • Domain logic that spans multiple aggregates
  • Stateless operations
  • Part of domain layer

Strategic Design

Context Mapping

Principle: Understand how bounded contexts relate to each other.

Relationship Types:

  • Shared Kernel: Shared model between contexts (use carefully)
  • Customer-Supplier: One context depends on another
  • Conformist: One context conforms to another's model
  • Anticorruption Layer: Translation layer between contexts
  • Separate Ways: Independent contexts with no relationship

Application:

  • Map relationships between contexts
  • Design integration points carefully
  • Use anticorruption layers when needed
  • Avoid shared kernels unless necessary

Tactical Design

Building Blocks

Aggregate Root:

  • Entity that controls access to aggregate
  • Enforces invariants
  • Maintains consistency
  • Single entry point for aggregate

Repository:

  • Interface for aggregate persistence
  • Hides infrastructure details
  • Domain-focused API
  • Implementation in infrastructure layer

Domain Events:

  • Things that happened in the domain
  • Past tense naming
  • Published by aggregates
  • Used for integration between contexts

Key Principles Summary

  1. Domain at Center: Business logic drives architecture
  2. Ubiquitous Language: Same language everywhere
  3. Bounded Contexts: Clear domain boundaries
  4. Domain Discovery First: Understand before modeling
  5. Strategic Design: Map context relationships
  6. Tactical Design: Use DDD building blocks

Related Documents

  • Systems Engineering Approach - Systems engineering principles
  • Documentation Process - DDD discovery process for documentation
  • Architecture Patterns - DDD architecture patterns and implementation

Source: Domain-Driven Design by Eric Evans, DDD principles and practices

Architecture OverviewDirectory Structure