ddd-architecture-awesome

Imported from partme-ai/workbuddy-agent-experts (experts/plugins/java-backend-team/skills/ddd-architecture-awesome/SKILL.md). Install upstream with npx skills add partme-ai/workbuddy-agent-experts --skill ddd-architecture-awesome. Copyright stays with the author (Apache-2.0).

DDD Architecture Awesome

The entry point to the DDD Skills ecosystem. This skill provides everything needed to understand DDD, decide if it's right for your project, and chart your learning path — all in one place.

When to Use (and When NOT to)

Start simple. Evolve complexity only when needed. Most systems don't need full CQRS or Event Sourcing.

When to trigger this skill

ALWAYS use this skill when the user mentions:

• "What is DDD", "Explain DDD", "DDD 是什么", "介绍一下 DDD"
• "Domain-Driven Design", "领域驱动设计"
• "DDD basics", "DDD fundamentals", "DDD 基础", "DDD 入门"
• "Should I use DDD", "DDD 适用场景", "DDD 是否适合"
• "DDD vs CRUD", "DDD vs traditional", "DDD 对比"
• "DDD concepts", "DDD 概念"
• "Strategic design DDD", "Tactical design DDD", "DDD 战略设计", "DDD 战术设计"
• "When to apply DDD", "When DDD is appropriate"
• Questions about DDD architecture types and their differences
• New to DDD and seeking guidance on where to start

1. DDD Definition

Domain-Driven Design is a development methodology that brings complex business rules into domain models: first define business boundaries (Strategic Design), then encode rules into models (Tactical Design).

Key insight: DDD is not about technology — it's about aligning your code with how the business thinks.

2. DDD Applicability Decision Tree

Evaluate along these dimensions and provide a "Suitable / Cautious / Not Recommended" conclusion:

Decision Flowchart

Is business logic complex (rules, state machines, constraints)?
├── NO → Is system long-lived (> 2 years)?
│         ├── NO → ✗ DDD NOT RECOMMENDED (Use simple CRUD + Service)
│         └── YES → ~ Cautious: adopt tactical patterns selectively
│
└── YES → Is there a domain expert or stable product owner?
          ├── NO → ~ Cautious: DDD without domain expert = complex code for nothing
          └── YES → Is the team familiar with DDD or willing to learn?
                    ├── NO → ~ Cautious: start with Layered, evolve later
                    └── YES → Do you need to swap infrastructure (DB, MQ)?
                              ├── NO → ✓ DDD RECOMMENDED (COLA or Layered)
                              └── YES → ✓ DDD STRONGLY RECOMMENDED (Hexagonal/Clean)

3. Complexity Ladder — Don't Skip Levels

Each level adds real complexity. Move up only when you've proven the current level insufficient.

Level 1: Simple Layered (Controller → Service → Repository)
   ↓ When business rules grow complex and need explicit modeling
Level 2: DDD 4-Layer with Rich Domain Model (Layered)
   ↓ When need multiple entry points (REST + CLI + MQ + gRPC)
Level 3: Ports & Adapters (Hexagonal Architecture)
   ↓ When read/write patterns diverge significantly
Level 4: CQRS — Separate Read/Write Models
   ↓ When need complete audit trail / temporal queries
Level 5: Event Sourcing — Store events, derive state

Your project Level: ___ (Recommend with reasoning)

4. Pattern Boundaries — What Each Pattern IS and IS NOT

This table solves the most common DDD confusion: "What's the difference between these patterns, and when should I use each one?"

5. DDD Architecture Landscape Overview

DDD Architecture Family:

  Foundational (Learning cost: Low → Medium):
  ├── Layered Architecture (分层架构)
  │   └── Classic 4-layer: Interface → Application → Domain ← Infrastructure
  │       1-5 people | CRUD-friendly | Spring Boot native
  │
  ├── Onion Architecture (洋葱架构)
  │   └── Domain core, concentric dependency rings, inner defines interface
  │       5-15 people | High testability | Frequent infra changes
  │
  ├── Hexagonal Architecture (六边形架构 / Ports & Adapters)
  │   └── Domain at center, ports define contracts, adapters implement
  │       5-15 people | Multi-entry systems | Best testability
  │
  Advanced (Learning cost: Medium → High):
  ├── Clean Architecture (整洁架构)
  │   └── Entities → Use Cases → Interface Adapters → Frameworks
  │       15-50 people | Enterprise systems | Strict module isolation
  │
  └── COLA Architecture (COLA v5 架构)
      └── Diamond pattern: Adapter → App → Domain ← Infrastructure
          5-50 people | Chinese enterprise | Best tooling & community

  Complementary Patterns:
  ├── CQRS — Separate read/write models (L1: Model only / L2: DB separation / L3: Event Sourcing)
  ├── Domain Events — Cross-aggregate eventual consistency
  └── Event Sourcing — Store events as source of truth

Architecture Visual Comparison

Layered        Onion        Hexagonal      Clean          COLA v5
┌────────┐   ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
│Interf. │   │ Infra    │  │ Adapter  │  │ Frame.   │  │ Adapter  │
├────────┤   │ ┌──────┐ │  ├──────────┤  ├──────────┤  ├──────────┤
│  App   │   │ │ App  │ │  │  Ports   │  │ Adapter  │  │   App    │
├────────┤   │ │┌────┐│ │  ├──────────┤  ├──────────┤  ├──────────┤
│ Domain │   │ ││Dom.││ │  │ Domain ★ │  │ Domain ★ │  │ Domain ★ │
├────────┤   │ ││ ★  ││ │  └──────────┘  └──────────┘  ├──────────┤
│ Infra  │   │ │└────┘│ │                              │ Infra    │
└────────┘   │ └──────┘ │                              └──────────┘
             └──────────┘

6. Core DDD Concepts Quick Reference

6.1 Strategic Design (战略设计)

6.2 Tactical Design (战术设计)

6.3 Quick Decision Trees

"Where does this code go?"

Where does this code go?
├─ Pure business logic, no I/O           → domain/
├─ Orchestrates domain + has side effects → application/
├─ Talks to external systems              → infrastructure/
├─ Defines HOW to interact (interface)    → port (domain or application)
└─ Implements a port                      → adapter (infrastructure)

"Entity or Value Object?"

Entity or Value Object?
├─ Has unique identity that persists → Entity
├─ Defined only by its attributes    → Value Object
├─ "Is this THE same thing?"         → Entity (identity comparison)
└─ "Does this have the same value?"  → Value Object (structural equality)

"Should this be its own Aggregate?"

Aggregate boundaries?
├─ Must be consistent together in a transaction → Same aggregate
├─ Can be eventually consistent                 → Separate aggregates
├─ Referenced by ID only                        → Separate aggregates
└─ >10 entities in aggregate                    → Split it

Rule: One aggregate per transaction. Cross-aggregate consistency via domain events (eventual consistency).

7. Rich Domain Model vs Anemic CRUD (Critical Distinction)

// ❌ Anemic Model (Anti-Pattern) — Data bag + Service
@Entity
public class Order {
    private Long id;
    private String status;       // String instead of Value Object
    // Only getters/setters, NO behavior
}

@Service
public class OrderService {       // God Service with all logic
    @Transactional
    public void pay(Long orderId) {
        Order order = orderRepo.findById(orderId);
        if ("DRAFT".equals(order.getStatus())) {  // Raw string comparison
            order.setStatus("PAID");
            orderRepo.save(order);
        }
    }
}

// ✅ Rich Domain Model (DDD) — Behavior WITH data
public class Order extends AggregateRoot<OrderId> {
    private OrderStatus status;      // Value Object
    private Money totalAmount;
    private List<OrderItem> items;

    public void pay() {              // Behavior in entity
        if (!status.canPay()) {
            throw new OrderException("Cannot pay in current status");
        }
        this.status = OrderStatus.PAID;
        addDomainEvent(new OrderPaidEvent(this.id));
    }
}

Aggregate Sizing Heuristics

8. Anti-Patterns (CRITICAL — with Fixes)

9. Implementation Order (Universal)

1. Discover the Domain — Event Storming, conversations with domain experts
2. Model the Domain — Entities, value objects, aggregates (NO infrastructure)
3. Define Ports — Repository interfaces, external service interfaces
4. Implement Use Cases — Application services coordinating domain
5. Add Adapters LAST — HTTP, database, messaging implementations

DDD is collaborative. Modeling sessions with domain experts are as important as code patterns.

10. How to Use This Skill

Step 1: Understand user context

Ask about: project nature, business complexity, team structure, current state.

Step 2: Assess DDD applicability

Run through the decision tree (Section 2) and output:

• Suitable: Proceed to architecture selection
• Cautious: Recommend selective adoption
• Not Recommended: Explain why, prevent over-engineering

Step 3: Recommend learning path

Step 4: Output format

Always structure response with:

1. 适用性评估 (Applicability Assessment) — clear conclusion + reasoning per dimension
2. DDD 核心概念速览 (Core Concepts Quick Reference) — tailored to context
3. 推荐学习路径 (Recommended Learning Path) — which skills, what order

11. Sources

完整来源清单（原著/模式参考/实施指南/中文资源/各语言参考实现）见 references/00-sources.md，按需加载。

Reference Library（按需加载）

This skill bundles a structured reference library organized by learning path. Each file is loaded only on demand — when the agent identifies the need.

How to use these references

When a user asks a question, find the matching category below and read the relevant file(s). Do NOT load all references at once.

End-to-End Examples

Examples differ from references: references teach concepts and principles; examples demonstrate application in concrete business contexts with real code. Load these when the user wants to see DDD applied to a realistic scenario.

Principle: "Don't apply DDD everywhere. Apply it where it matters."

After this, use ddd-architecture-selector to choose the right architecture pattern, then dive into domain modeling with ddd-domain-designer and implementation with the specific architecture skill.

Gotchas — Common Pitfalls

• "DDD = COLA" 误解: DDD 不是等于 COLA 框架。COLA 只是阿里体系中一种落地方案。还有 Layered、Onion、Hexagonal、Clean 等多种架构可选。根据项目实际需求选择。
• 一上来就搞 CQRS + Event Sourcing: 绝大多数项目不需要 Event Sourcing。先评估是否真的需要完整审计追踪和时间旅行查询。从最简单的分层架构开始。
• 把 DDD 当银弹: DDD 适合复杂业务领域，对于简单 CRUD 项目反而是过度设计。判断标准：业务规则 > CRUD 操作，有领域专家参与，需要长期维护。
• 战术设计先于战略设计: 直接写 Entity/ValueObject 而不先做 Bounded Context 划分。没有战略边界的战术设计会导致上下文混乱和模型冲突。
• 领域专家参与不足: DDD 需要领域专家持续参与。开发人员凭自己对业务的理解建模，产出的模型很可能偏离真实业务。

When NOT to Use This Skill

Security & Stability

• All code examples and concept illustrations are for educational purposes. They contain no real credentials or sensitive data.
• This skill teaches DDD methodology and patterns. It does not execute code, access external systems, or modify any project files.
• DDD's bounded context isolation naturally promotes security boundaries between different parts of the system.
• No executable scripts bundled. This skill is a pure learning and reference resource.

🧭 DDD Skills Journey

📍 You are here: ddd-architecture-awesome — Step 1: DDD 入门与全景

flowchart LR
    S1["⭐ Step 1<br/>awesome<br/>入门与全景"] --> S2["Step 2<br/>selector<br/>架构选型"]
    S2 --> S3A["Step 3<br/>layered<br/>分层架构"]
    S2 --> S3B["Step 3<br/>onion<br/>洋葱架构"]
    S2 --> S3C["Step 3<br/>hexagonal<br/>六边形架构"]
    S2 --> S3D["Step 3<br/>clean<br/>整洁架构"]
    S2 --> S3E["Step 3<br/>cola<br/>COLA v5"]
    S3A & S3B & S3C & S3D & S3E --> S4A["Step 4<br/>domain-designer<br/>领域建模"]
    S3A & S3B & S3C & S3D & S3E --> S4B["Step 4<br/>cqrs-architecture<br/>CQRS"]
    S3A & S3B & S3C & S3D & S3E --> S4C["Step 4<br/>api-designer<br/>API设计"]
    S4A & S4B & S4C --> S5["Step 5<br/>code-reviewer<br/>代码审查"]
    S5 --> S6A["Step 6<br/>event-storming<br/>事件风暴"]
    S5 --> S6B["Step 6<br/>testing-strategist<br/>测试策略"]
    S5 --> S6C["Step 6<br/>devops-integration<br/>DevOps"]
    S5 --> S6D["Step 6<br/>evaluator<br/>架构评估"]
    S6A & S6B & S6C & S6D --> S7["🏁 Step 7<br/>architecture-doc<br/>架构文档"]

    style S1 fill:#10b981,stroke:#059669,color:white,stroke-width:3px

← Previous: 你已经在 DDD 旅程的起点 🚀 → Next: hand off to ddd-architecture-selector skill — 选择适合你项目的架构模式(Install: npx skills add full-stack-skills/ddd-skills --skill ddd-architecture-selector). 🔗 Related: hand off to ddd-domain-designer skill — 直接开始领域建模(Install: npx skills add full-stack-skills/ddd-skills --skill ddd-domain-designer) | ddd-event-storming skill — 先做事件风暴工作坊(Install: npx skills add full-stack-skills/ddd-skills --skill ddd-event-storming). 🏠 Home: 你在起点

💡 你是第一次接触 DDD？读完 Section 4 的 Pattern Boundaries 表和 Section 6 的核心概念速查，然后去 selector 选架构。