/nw-legacy-refactoring-ddd

name: nw-legacy-refactoring-ddd
description: DDD-guided legacy refactoring patterns -- strangler fig, bubble context, ACL migration, 14 tactical/strategic/infrastructure patterns, and incremental monolith-to-microservices methodology
user-invocable: false
disable-model-invocation: true

Legacy Refactoring with DDD

Refactoring legacy systems using Domain-Driven Design as the strategic compass. DDD tells you WHERE and WHY to refactor; traditional techniques (progressive-refactoring, mikado-method) tell you HOW.

Principle: "Start simple, grow big" -- incremental steps tested at each stage.

Decision Framework: Before Refactoring

Ask three questions before any DDD refactoring: 1. **Business value**: what business outcome does refactoring this area enable? 2. **Risk**: what breaks if we refactor vs. if we do not? 3. **Cost**: time, effort, disruption -- is it justified?

When NOT to Refactor

• System scheduled for replacement
• Stable system with no new development
• Cost exceeds benefit
• Team lacks DDD experience with no learning budget
• Domain is genuinely simple (CRUD-dominated)

Cynefin-Refactoring Mapping

| Cynefin Domain | Refactoring Approach | |---------------|---------------------| | Clear | Apply established patterns directly; standard refactoring catalogs | | Complicated | Analyze with experts, then apply patterns; multiple valid solutions | | Complex | Probe with safe-to-fail experiments; EventStorming to discover patterns | | Chaotic | Act first to stabilize, then refactor; emergency patches acceptable | | Confusion | Gather information before deciding; avoid premature refactoring |

Migration Methodology (4 Phases)

Phase 1: Understand and Stabilize

1. Run EventStorming to map current system (Big Picture) 2. Assess complexity using Cynefin framework 3. Write characterization tests for critical paths (Feathers technique) 4. Identify bounded contexts in existing codebase via language divergence

Phase 2: Modularize the Monolith

1. Introduce module structure aligned with bounded contexts 2. Use mediator pattern for initial decoupling between modules 3. Apply fitness functions to measure progress (coupling, cohesion, dependency direction) 4. Refactor database schemas toward context alignment

Phase 3: Introduce Events and CQRS

1. Replace mediator with event-driven communication 2. Implement CQRS for contexts benefiting from read/write separation 3. Split databases per bounded context using expand/contract pattern 4. Use event-based data synchronization for cross-context data needs

Phase 4: Extract Services (if justified)

1. Evaluate microservices readiness (6 signals below) 2. Start with most independent bounded context 3. Use strangler fig pattern -- incrementally extract while legacy still runs 4. Apply appropriate saga pattern for distributed transactions

Microservices Readiness Signals

1. Clear domain boundaries already established 2. Scaling pressure on specific areas (not uniform) 3. Independent development needs across teams 4. Operational maturity (CI/CD, monitoring, automated testing in place) 5. Technical expertise in distributed systems 6. Business justification (not trend-following)

Strategic Refactoring Patterns

Strangler Fig

Build new DDD-modeled functionality alongside legacy. Route requests to new code as features complete. Legacy gradually shrinks until fully replaced. Changes are incremental, monitored, low risk of unexpected breakage.

**Mikado integration**: use Mikado exploration to discover dependencies between legacy components before extracting. Each Mikado leaf becomes an atomic refactoring step.

Bubble Context

Create a small bounded context (the "bubble") where DDD principles apply. The bubble communicates with legacy through an Anti-Corruption Layer. Progressively expand the bubble to encompass more legacy functionality.

**Steps**: 1. Identify the most valuable bounded context (core domain) for initial DDD investment 2. Create an ACL between the new context and legacy 3. Apply tactical DDD within the bubble (aggregates, value objects, domain events) 4. Gradually expand, moving more logic behind the ACL 5. Retire legacy components as new context absorbs their functionality

Evolve Context Map

Integration patterns change as refactoring progresses. Map current relationships, identify mismatches, propose new patterns. Typical evolution: Conformist -> Customer-Supplier with ACL -> Partnership.

Split Bounded Context

When a context grows too large or serves conflicting purposes: 1. Domain decomposition to break responsibilities into subdomains 2. Context mapping to plan the split and redefine integration patterns 3. Isolate related aggregates 4. Introduce domain events for communication 5. Gradually refactor dependent code

Validation: bounded context splits are driven by business evolution, not technical convenience. Validate with domain experts.

Merge Bounded Contexts

When separation causes more friction than value: 1. Identify redundancies (overlapping models, duplicate logic, tight coupling) 2. Establish unified ubiquitous language 3. Consolidate aggregates and deprecate redundant events 4. Revisit context map

Tactical Refactoring Patterns

These patterns apply tactical DDD concepts (aggregates, value objects, domain events, domain services, CQRS) to refactoring. For foundational definitions and design rules, load `domain-driven-design` from `solution-architect/`.

| Pattern | What It Fixes | Key Step | |---------|--------------|----------| | Replace primitives with VOs | Primitive obsession | Create self-validating type, replace in aggregate, update mapping | | Enrich anemic model | Logic in services, data in entities | Move business rules from service "if" statements into owning entity | | Introduce domain events | Direct coupling between aggregates | Replace method calls with immutable past-tense events + handlers | | Extract domain service | Cross-aggregate operations in