ddd-modeling

DDD Modeling

Ortak Doktrin

agents/shared/severity-rubric.md ve agents/shared/escalation-matrix.md default-load sayılır (agents/coordination.md §11). Bu skill'in çıktısı Critical / High / Medium / Low + kanıt formatında olmak zorunda — spekülatif Critical yasak. Sahiplik dışı bulgu ilgili agent'a delege; karar yetkisi eşiği aşılırsa kullanıcı onayı zorunlu.

Felsefe

• Domain önce, technology sonra. Ubiquitous language → model → schema.
• Bounded context = anlam birimi. "Order" iki context'te farklı şey olabilir.
• Aggregate küçük + transaction boundary. Cross-aggregate eventual consistency.
• Domain event olay-kaynağı kaydı. State değil olay.
• Microservice ≈ bounded context (ideal); aksi domain sızıntısı.

Ne Zaman Kullanılır

• Yeni domain modeling (/discovery sonrası, kod yazılmadan)
• Mikroservis decomposition (monolith → service)
• Cross-team koordinasyon (aynı kelime farklı anlam çakışması)
• Legacy refactor (Anemic Domain Model → DDD)
• Event-driven architecture tasarımı
• Bounded context iletişim çatışması
• Domain glossary üretimi
• New domain expert onboarding

Workflow

1) Strategic discovery (Event Storming)

Workshop format (3-4 saat, 5-12 katılımcı):

1. Domain event keşfet (kahverengi sticky note):
   • "OrderConfirmed", "PaymentCaptured", "InventoryReserved".
   • Past tense + business-meaningful.
2. Timeline (sol → sağ akış).
3. Aktörler (sarı): "Customer", "Admin", "Payment Provider".
4. Komut (mavi): "ConfirmOrder", "CapturePayment".
5. Aggregate'ler (sarı büyük): event'leri groupla.
6. Bounded context sınırları kalın çizgi.
7. Hot spot (kırmızı): "burası belirsiz / iki team çakışıyor".

Çıktı:

• Bounded context haritası (3-7 context ideal).
• Domain event listesi (40+ event'e kadar).
• Hot spot listesi → ADR adayı.

2) Bounded context tanımı

Her context için bir bounded context canvas:

## Bounded Context: Orders

### Purpose
Customer satın alma intent'inin lifecycle yönetimi (created → paid → shipped).

### Strategic Classification
- **Core domain** (rekabet avantajı).
- Sahip ekip: @orders-team.

### Ubiquitous Language
- Order: müşterinin satın alma niyeti.
- OrderLine: bir Order içindeki satın alınan kalem (SKU + qty).
- Status: created | pending_payment | paid | shipped | delivered | cancelled.
- (terms tanımlı, glossary `docs/glossary/orders.md`.)

### Domain Events (yayınladıklarımız)
- OrderCreated, OrderConfirmed, OrderPaid, OrderShipped, OrderCancelled.

### Domain Events (dinlediklerimiz)
- PaymentCaptured (Billing context'ten).
- InventoryReserved (Inventory context'ten).

### Inbound (API)
- POST /v1/orders (CreateOrder command)
- POST /v1/orders/{id}/confirm
- GET /v1/orders/{id}

### Outbound
- PaymentService.CapturePayment (HTTP)
- InventoryService.Reserve (HTTP)

### Persistence
- Postgres `orders` DB (kendi DB).

### Team
- @orders-team (4 dev, 1 PM).

3) Context Map (ilişki pattern'leri)

graph LR
  CRM[CRM context]
  ORD[Orders context]
  BIL[Billing context]
  INV[Inventory context]
  NOT[Notification context]

  CRM -- "Conformist" --> ORD
  ORD -- "OHS + PL (REST)" --> BIL
  ORD -- "OHS + PL" --> INV
  ORD -- "Published events" --> NOT
  BIL -. "Anti-Corruption Layer" .-> StripeProvider[Stripe External]

Her edge için:

• Pattern (Conformist / OHS / ACL / Shared Kernel / Customer-Supplier / Partnership).
• Iletişim tipi (sync HTTP / async event / shared DB — ihlal!).
• SLA / contract referansı (OpenAPI / AsyncAPI dosyası).

4) Tactical design (her bounded context için)

Aggregate identification

• 1-3 entity per aggregate (small aggregates).
• Consistency boundary = transaction scope.
• Cross-aggregate eventual consistency (domain event ile).

Entity / Value Object ayırımı

• Identity önemli mi? → Entity.
• Equality value-based mi? → Value Object (immutable, dataclass frozen).

Repository abstraction

• Application layer'da Protocol/Interface; infra layer'da concrete impl.
• ORM detay infra'da (SQLAlchemy decorator domain entity'de yasak).

Domain service

• Cross-aggregate koordinasyon.
• External system contract (price calc, fraud check).

Application service (use case)

• Transaction script: command → aggregate çağrı → repository.save → event publish.

5) Microservice boundary önerisi

Bounded context = mikroservis (ideal). Şartlar:

• Bounded context'ler bağımsız deploy edilebilir.
• Cross-context iletişim published language üzerinden.
• DB paylaşılmaz (bounded context'in kendi DB).

Anti-corruption layer (ACL):

• Legacy / 3rd party / başka context'ten dil çevir.
• Domain modeli yabancı dil kirletmesin.

# Anti-corruption layer örnek
class StripeACL:
    """Stripe API → Billing domain çevirisi."""
    def to_payment_intent(self, stripe_response: dict) -> PaymentIntent:
        return PaymentIntent(
            id=PaymentIntentId(stripe_response["id"]),
            amount=Money(Decimal(stripe_response["amount"]) / 100,
                         Currency(stripe_response["currency"])),
            status=self._map_status(stripe_response["status"]),
        )

6) Domain glossary

docs/glossary/<context>.md:

# Orders Context — Ubiquitous Language

| Term | Tanım | Anti-tanım (ne değil) |
|---|---|---|
| Order | Customer satın alma niyeti. Lifecycle: created → confirmed → paid → shipped → delivered. | Faturalanacak kalem değil (Billing context'in Order'ı). |
| OrderLine | Order içindeki bir SKU+qty. | Inventory rezervasyonu değil. |
| ... |

Cross-context translation tablosu:

## Cross-Context: "Order" disambiguation

| Bizim Order | Karşı tarafın terimi | Çevirici |
|---|---|---|
| Orders.Order | Billing.Invoice | ACL: OrderConfirmed event → InvoiceCreated |
| Orders.Order | Inventory.Reservation | ACL: OrderCreated event → ReservationRequest |

7) Migration / extraction plan

Monolith → microservice extraction (migration-planner delege):

1. Bounded context tespit (event storming).
2. Strangler Fig: yeni servis bir parça alır.
3. Repository abstraction önce (DB encapsulation).
4. Aggregate extract.
5. Domain event publish.
6. Cross-service ACL yaz.
7. Eski code path drop.

Checklist

• Event storming workshop yapıldı (4 saat min)
• Bounded context haritası (3-7 context)
• Domain event listesi (past tense, business-meaningful)
• Context map (8 pattern'den biri her edge için)
• Aggregate identification (small, 1-3 entity)
• Entity / Value Object ayrımı
• Repository abstraction (infra leak yok)
• Application service (use case) layer
• Anti-Corruption Layer (3rd party / legacy / cross-context)
• Domain glossary per-context
• Microservice boundary önerisi (bounded context = service)
• Hot spot → ADR adayı
• Cross-team translation tablosu

Antipattern

• Anemic Domain Model — getter/setter sınıf, logic service'te.
• Big Ball of Mud — sınır yok.
• Shared DB across microservice — bounded context ihlali.
• Cross-aggregate transaction — eventual consistency tercih.
• Ubiquitous language sessiz değişim — glossary güncelle, ekibe ilan.
• Anemic event (OrderUpdated) — domain-meaningful (OrderConfirmed).
• Domain'de ORM leak — SQLAlchemy decorator entity'de.
• Getter/setter spam — invariant method'la kapsülle.
• God Aggregate — 10+ entity tek aggregate.
• Bounded context kopyala-yapıştır — ACL ile ayır.
• Microservice = teknik split (REST API ayırma) — domain ayırma şart.
• Event storming yok — domain model gut-feeling.

Örnek Agent Davranışı

User: /ddd-model payments-platform
Agent (product-domain-analyst + system-design-architect):
1. Event storming workshop önerir — 4 saat, 8 katılımcı.
2. 47 domain event listele.
3. 5 bounded context çıkar:
   - Orders (core)
   - Billing (core)
   - Inventory (supporting)
   - Notification (generic)
   - CRM (legacy, anti-corruption layer)
4. Context map: Mermaid + 5 edge (4 OHS+PL + 1 ACL CRM'e).
5. Tactical: Orders context için 2 aggregate (Order + Cart);
   8 value object; 6 domain event.
6. Domain glossary `docs/glossary/orders.md` + cross-context translation.
7. 3 hot spot → 3 ADR önerisi (`architecture-decision-writer` delege).
8. Microservice boundary: 5 service önerisi (1 = 1 context).
9. Migration plan (mevcut monolith): 6-12 ay Strangler Fig phase.
10. Output: docs/ddd/payments-platform/ + 5 bounded context canvas + Mermaid.