DDD Architecture Selector

Architecture selection decision guide that evaluates 5 DDD architecture patterns (Layered, Onion, Hexagonal, Clean, COLA) against project context — team size, business complexity, tech stack, infrastructure change frequency, and ecosystem preference.

Workflow

Step 1: Collect Project Context

• Team size & DDD experience level
• Business complexity (simple CRUD / moderate / high)
• Technical stack (Spring Boot / Go / Node.js / .NET / Python)
• Infrastructure change frequency (low / medium / high)
• Multi-entry needs (REST + CLI + MQ + gRPC?)
• Test coverage requirements (unit / integration / E2E)
• Ecosystem preference (Chinese community / international)

Step 2: Run Decision Matrix

• Compare 5 architectures across 7+ dimensions

Step 3: Apply Decision Tree

• Complexity → Team Size → Tech Stack → Recommended Architecture

Step 4: Recommend CQRS Level

• L0: None, L1: Model Separation, L2: DB Separation, L3: Event Sourcing

Step 5: Classify Domain Types

• Core / Generic / Supporting → Apply different architectures per domain

Step 6: Suggest Microservice Splitting

• One BC → One Service, with merge/split rules

Step 7: Route to Specific Architecture Skill

• Link to detailed implementation guidance

When to Use (and When NOT to)

Boundary

Audience

This skill is designed for: Backend developers (implementing DDD architectures), Software architects (evaluating and selecting patterns), Tech leads (reviewing team implementations), and DDD beginners (learning domain-driven design fundamentals).

Rules

1. Architecture selection must evaluate at least 5 dimensions.
2. Never recommend Event Sourcing as default — only after L2 CQRS success.
3. Team size and domain complexity must be the primary selection factors.

5-Architecture Decision Matrix

| Dimension | Layered | Onion | Hexagonal | Clean | COLA | |-----------|:--:|:--:|:--:|:--:|:--:| | Learning Cost | ★☆☆ | ★★★ | ★★★ | ★★★ | ★★☆ | | Business Complexity Fit | ★☆☆ | ★★★ | ★★★ | ★★★ | ★★★ | | CRUD Efficiency | ★★★ | ★☆☆ | ★☆☆ | ★☆☆ | ★★☆ | | Infrastructure Replaceability | ★☆☆ | ★★★ | ★★★ | ★★★ | ★★☆ | | Test Friendliness | ★☆☆ | ★★★ | ★★★ | ★★★ | ★★★ | | Chinese Community | ★★★ | ★☆☆ | ★☆☆ | ★☆☆ | ★★★ | | Code Generation Support | Good | Poor | Poor | Poor | Excellent | | Module Physical Isolation | Low | Medium | Medium | High | High | | Evolution Path Clarity | ★☆☆ | ★★★ | ★★★ | ★★★ | ★★★ | | Team Size Fit | 1-5 | 5-15 | 5-15 | 15-50 | 5-50 | | Origin | Martin Fowler | Jeffrey Palermo (2008) | Alistair Cockburn (2005) | Robert C. Martin (2012) | Alibaba (2018) |

3-Step Decision Tree

Step 1: Assess Business Complexity

Business Complexity?
│
├── Simple CRUD (80%+ CRUD operations)
│   └── Planning DDD adoption in future?
│       ├── No  → LAYERED ARCHITECTURE
│       └── Yes → COLA Simplified (single module)
│
├── Moderate (core business logic with rules)
│   ├── Chinese ecosystem / Spring Boot + MyBatis?   → COLA
│   ├── Value domain layer purity most?               → HEXAGONAL
│   ├── Multi-entry system (REST + CLI + MQ)?         → HEXAGONAL
│   ├── Infrastructure changes often?                 → HEXAGONAL / ONION
│   └── .NET / Python stack?                          → ONION
│
└── High (multiple BCs, microservices)
    ├── Enterprise / international team?              → CLEAN ARCHITECTURE
    ├── Chinese enterprise, per-service standards?     → COLA (multi-module)
    ├── Mixed tech stack per service?                 → HEXAGONAL per service
    └── Need microservice + standard per module?      → COLA + HEXAGONAL hybrid

Step 2: Match Team Size

Evolution Path: Team grows → upgrade architecture progressively: 1-5 (Layered) → 5-15 (Hexagonal) → 15-50 (Clean/COLA) → 50+ (Microservices+Hex).

Step 3: Final Recommendation

Domain Partitioning + Microservice Splitting

Domain Classification (Core / Generic / Supporting)

Key rule: Don't apply Hexagonal or Clean to generic/supporting domains — it wastes effort. Reserve complex architectures for Core domains only.

Microservice Splitting Rules

1. Default: One Bounded Context → One Microservice
2. Split when: Different deployment cadence, different scaling needs, different team ownership
3. Merge when: Strong transactional consistency needed, small context (< 2 weeks dev), same team
4. Start conservative: Fewer services, split as needed (proven by need, not anticipation)
5. Communication: Events for eventual consistency, RPC for strong consistency (rare)

CQRS Level Suggestion

Recommendation: Start at L0, prove need for higher levels. L2+ should only be adopted alongside Hexagonal or Clean architectures for proper port isolation.

Architecture Skill Navigation

Related: ddd-cqrs-architecture / ddd-domain-designer / ddd-architecture-evaluator (each installable via npx skills add full-stack-skills/ddd-skills --skill <name>)

Gotchas

See [references/gotchas.md](references/gotchas.md) for 15 pitfalls.

FAQ

See [references/faq.md](references/faq.md) for 15 Q&A.

Security & Safety

This skill is pure documentation. It does not collect user data, does not access external services or networks, and contains no executable scripts.

References

See [references/](references/) for deep comparisons, microservice/domain, clean+DDD+hexagonal, ddd4j analysis, gotchas, FAQ, external resources, and 5 case studies.