---
name: ddd-modeling
description: Domain-Driven Design — bounded context + ubiquitous language + context map + aggregate + entity + value object + domain event + event storming. Mikroservis boundary; multi-team büyük domain.
---

# 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**:

```markdown
## 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)

```mermaid
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.

```python
# 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`:

```markdown
# 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:
```markdown
## 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.
```