ddd-module-pattern

DDD module pattern

"Modules should reflect the concepts of the domain, not technical concerns." — Eric Evans, Domain-Driven Design (2003)

Core Principles

Package names in the domain layer are part of the ubiquitous language.

Problem: Technology-Driven Packaging

domain/
  entities/           ← ❌ 技術的分類
    Order.java
    Customer.java
  value-objects/      ← ❌ 技術的分類
    Money.java
    OrderId.java
  services/           ← ❌ 技術的分類
    OrderService.java

Issue	Impact
Domain structure is invisible	Looking at the packages, you cannot tell the shape of the business
Reduced cohesion	Related concepts are scattered across different folders
Ripple effects of change	A single feature change crosses multiple folders

Solution: Domain-Driven Packaging

domain/
  order/              ← ✅ ドメイン概念
    Order.java
    OrderId.java
    OrderItem.java
  customer/           ← ✅ ドメイン概念
    Customer.java
    CustomerId.java
  pricing/            ← ✅ ドメイン概念
    PricingPolicy.java
    Money.java

Benefit	Effect
Visualization of the domain	Package list = the main concepts of the domain
High cohesion	Related types are consolidated in the same package
Localized changes	A feature change is completed within one package

Detection Patterns

Package names to avoid (domain layer)

❌ entities/
❌ value-objects/ (valueobjects/, vo/)
❌ aggregates/
❌ services/
❌ interfaces/
❌ impl/
❌ dto/
❌ domain/types/
❌ domain/core/

Review checklist

Package name test: Does it make sense to a business person?
- ✅ order, billing, inventory → Business term
- ❌ entities, services, impl → Technical term
Cohesion test: Do they belong to the same business context?
- ✅ order/ に Order, OrderItem, OrderId
- ❌ entities/ に Order, Customer, Product
Change impact test: How many packages does one business requirement touch?
- ✅ 1-2 packages
- ❌ 3 or more packages

Refactoring Steps

Step 1: Extract domain concepts

現状分析:
- Order, OrderId, OrderItem → 「注文」概念
- Customer, CustomerId → 「顧客」概念
- Money, PricingPolicy → 「価格設定」概念

Step 2: Determine package boundaries

order/
customer/
pricing/

Step 3: Move and update references

Move types to the new package and update import statements.

Step 4: Verify dependency direction

✅ order → pricing (注文が価格計算を使う)
❌ pricing → order (循環の可能性)

Language-Specific Guidance

For details, see references/language-guides.md .

Exceptions and Caveats

Shared Kernel

Basic types used across multiple domains may be placed in a shared package:

domain/
  shared/           ← 許容される例外
    Money.java
    DateRange.java
  order/
  customer/

However shared/ bloat is a sign to reconsider the design.

The infrastructure layer has different rules

Technology-driven packaging is also acceptable outside the domain layer：

infrastructure/
  persistence/      ← 技術的分類OK
    jpa/
    redis/

Small domains

If there are fewer than 10 types, a single level is sufficient. If it exceeds that, consider subpackages.

References

Evans, Eric. "Domain-Driven Design" (2003), Chapter 5: Modules
Vernon, Vaughn. "Implementing Domain-Driven Design" (2013), Chapter 9: Modules

Related Skills (recommended reading)

When using this skill, also refer to the following skills:

package-design: Package design principles that form the foundation of module design
clean-architecture: Layer structure for placing domain modules
domain-building-blocks: Design of building blocks placed within modules