Domain Driven Design rules file

domain-driven-design.md

Domain Driven Design (DDD)

Strategic design methodology focusing on modeling complex business domains through collaboration between domain experts and developers. Emphasizes creating a shared understanding of the business domain through ubiquitous language and bounded contexts.

Context

Apply DDD principles when building complex business applications where domain complexity is the primary challenge.

Applies to: Complex business domains, enterprise applications, microservices architectures
Level: Strategic/Tactical - guides both high-level architecture and implementation patterns
Audience: Developers, Architects, Domain Experts, Product Teams

Core Principles

1. Ubiquitous Language: Use domain-specific terminology consistently across code, documentation, and conversations
2. Model-Driven Design: The domain model should drive the software design, not technical concerns
3. Bounded Context: Define clear boundaries where a particular model applies and is valid

Rules

Must Have (Critical)

• RULE-001: All domain logic MUST be encapsulated within domain entities, value objects, or domain services
• RULE-002: Domain models MUST be free of infrastructure dependencies (repositories, databases, frameworks)
• RULE-003: Use ubiquitous language consistently in code - class names, methods, and variables MUST match domain terminology

Should Have (Important)

• RULE-101: Aggregate roots SHOULD control access to entities within their boundary
• RULE-102: Domain events SHOULD be used to communicate between bounded contexts
• RULE-103: Repository interfaces SHOULD be defined in the domain layer, implemented in infrastructure

Could Have (Preferred)

• RULE-201: Consider using specification pattern for complex business rules
• RULE-202: Implement factories for complex aggregate creation logic
• RULE-203: Use domain services for operations that don't naturally belong to a single entity

Patterns & Anti-Patterns

✅ Do This

// Rich domain model with business logic
public class ProductIncident {
    private IncidentReference reference;
    private ProductCode productCode;
    private IncidentStatus status;
    
    public void resolve(ResolutionNotes notes) {
        if (!canBeResolved()) {
            throw new IncidentCannotBeResolvedException();
        }
        this.status = IncidentStatus.RESOLVED;
        recordEvent(new IncidentResolvedEvent(reference, notes));
    }
}

❌ Don't Do This

// Anemic domain model with getters/setters
public class ProductIncident {
    public String getStatus() { return status; }
    public void setStatus(String status) { this.status = status; }
    // No business logic - violates DDD principles
}

Decision Framework

When rules conflict:

1. Domain model integrity takes precedence over technical convenience
2. Ubiquitous language consistency overrides technical naming conventions
3. Business rules in domain layer override performance optimizations

When facing edge cases:

• Consult domain experts to refine the model
• Consider if you've identified a new bounded context
• Evaluate if the complexity warrants DDD approach

Exceptions & Waivers

Valid reasons for exceptions:

• Simple CRUD operations with minimal business logic (consider if DDD is needed)
• Performance-critical paths (document trade-offs clearly)
• Legacy integration constraints (temporary, with migration plan)

Process for exceptions:

1. Document the exception and business justification
2. Review with domain experts and technical leads
3. Plan remediation if technical debt is introduced

Quality Gates

• Automated checks: Domain layer must not depend on infrastructure packages
• Code review focus: Verify ubiquitous language usage and domain logic placement
• Testing requirements: Domain model must be testable without infrastructure dependencies

Related Rules

• rules/clean-architecture.md - Complementary architectural patterns
• rules/testing-strategy.md - How to test domain models effectively
• rules/microservices-boundaries.md - Bounded context implementation in distributed systems

References

• Domain-Driven Design: Tackling Complexity in the Heart of Software - Eric Evans
• Implementing Domain-Driven Design - Vaughn Vernon
• DDD Reference - Eric Evans' summary

---

TL;DR

Key Principles:

• Model the business domain, not technical concerns
• Use ubiquitous language consistently everywhere
• Define clear bounded contexts with explicit boundaries

Critical Rules:

• Must keep domain logic in domain layer only
• Must not reference infrastructure from domain
• Always use domain terminology in code

Quick Decision Guide: When in doubt: Ask "Does this serve the business domain or technical infrastructure?" Domain wins.