microservice-extraction

Microservice Extraction

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

• Bounded context first — DDD model olmadan extraction yapma.
• Strangler Fig — big-bang yasak.
• Anti-Corruption Layer — legacy model boundary'de kal.
• Database per service — shared DB = distributed monolith.
• API contract pre-commit — consumer-driven.
• Reversibility — 90 gün rollback.
• Operational readiness — SLO + alert + runbook + on-call.

Ne Zaman Kullanılır

• Monolith'ten ilk microservice extraction kararı
• Distributed monolith smell — geri tasarım
• Bounded context split planı
• Team velocity blocker (independent deploy gerek)
• PCI / HIPAA scope reduction (extraction)
• Conway's law re-alignment (yeni team yapısı)
• Schema split (shared DB → ayrı)

Workflow

1) Domain analysis

/ddd-model ile başla. Output: bounded context map + ubiquitous language + aggregate.

identity-context
commerce-context
payments-context
fulfillment-context
billing-context

2) Extraction prioritization

Her context için skor (1-5):

Kriter	Score
Deploy frequency need	1-5
Compliance isolation value	1-5
Scaling profile differ	1-5
Team boundary clarity	1-5
Coupling depth (5 = düşük coupling)	1-5
Risk (5 = düşük risk)	1-5

Toplam ≥ 24 → adopt; ≥ 18 → trial; < 18 → hold.

İlk extraction önerisi: düşük risk + yüksek değer + bounded clarity.

Örn: notifications (28), search (26), reporting (24). İlk extraction yasak: payments (16, yüksek risk), core checkout (12).

3) ADR yaz

/architecture-decision-writer delege. Karar bağlamı + alternatifler + sonuçlar.

4) Strangler Fig phase planı

Phase 1 (2 hafta): Façade + yeni servis scaffold
  - API gateway routing rule `/api/v2/notifications` → new-svc
  - new-svc skeleton (catalog-info, SLO, runbook, on-call)

Phase 2 (1 ay): Yeni endpoint new-svc'de implement (greenfield)
  - Eski endpoint hala monolith'te
  - Yeni traffic %1 → %10 (feature flag)
  - Guardrail: latency, error, business metric

Phase 3 (1 ay): Migration eski endpoint → new-svc
  - Dual-write veya shadow read pattern
  - Backfill chunked

Phase 4 (1 ay): Cutover
  - Read-from-new exclusive
  - Monolith fallback flag still on

Phase 5 (1 ay): Cleanup
  - 90 gün geçti
  - Monolith eski kod sil
  - Fallback flag remove

Phase 6 (DB split, ihtiyaç varsa):
  - Shared schema → ayrı schema → ayrı DB instance

5) ACL implementation

# new-svc — clean domain
@dataclass
class Notification:
    recipient: UserId
    channel: Channel        # Enum: EMAIL | SMS | PUSH
    template: TemplateId
    locale: Locale
    payload: dict

# legacy adapter (ACL boundary)
class LegacyNotificationAdapter:
    def from_legacy(self, l: LegacyMonolithNotification) -> Notification:
        return Notification(
            recipient=UserId(l.user_id),
            channel=self._map_channel(l.delivery_method),
            template=TemplateId(l.template_key or "default"),
            locale=Locale(l.lang or "en"),
            payload=self._migrate_payload(l.data),
        )

    def _map_channel(self, legacy: str) -> Channel:
        return {
            "EMAIL_NOTIF": Channel.EMAIL,
            "SMS_NOTIF": Channel.SMS,
            "PUSH_NOTIF": Channel.PUSH,
            "EML": Channel.EMAIL,            # legacy bug
        }[legacy]

ACL boundary'de durur; içeri sızmaz.

6) Consumer-driven contract

pact-broker setup:

# consumer (web-frontend)
npx jest --testPathPattern=__pact__
pact-broker publish pacts/ --consumer-app-version=$GIT_SHA

# provider (notifications-svc)
pact-broker can-i-deploy --pacticipant notifications-svc \
  --version=$GIT_SHA --to-environment=production

CI gate: contract uyumlu değilse PR red.

7) Operational readiness gate

/production-ready skill:

[x] catalog-info.yaml + owner (Backstage)
[x] SLO doc (latency p99 < 300ms, availability 99.9%)
[x] PagerDuty rotation
[x] Runbook published (TechDocs)
[x] Structured log + trace + RED dashboard
[x] Threat model done
[x] Snyk Critical = 0
[x] k6 load test baseline (capacity-plan)
[x] Rollback drill ≥ 1 staging
[x] ADR Accepted
[x] Feature flag fallback (90 gün)

Eksik kalem varsa extraction PR red.

8) Database split

/data-migration skill:

A (shared DB shared schema):  monolith + new-svc public.notifications
B (shared DB, ayrı schema):   public.notifications_v2 (new-svc owner)
C (dual-write):               monolith → both
D (backfill):                 chunked migration
E (shadow read):              new-svc reads new + verify
F (cutover):                  new-svc reads exclusive
G (DB instance split):        ayrı RDS / pod (mesh DNS)
H (cleanup):                  eski schema drop

9) Saga / Outbox (varsa distributed transaction)

-- outbox pattern
begin;
insert into orders (...);
insert into outbox (event_type, payload) values ('OrderCreated', '{...}');
commit;
-- background poller publishes outbox → Kafka/NATS

Consumer idempotent (at-least-once delivery).

10) Rollback window (90 gün)

• Feature flag route_to_new_svc
• Canary %1 → %10 → %50 → %100
• Rollback drill staging + production on-call practice
• 90 gün sonra eski kod sil (commit + tag)

Distributed Monolith Smell Check

Smell	Var	Mitigation
N servis hep birlikte deploy	⚠	Independent CD pipeline
Shared DB sustained	⚠	Phase 6 split
Sync call chain > 3 hop	⚠	Saga / cache / API redesign
Tek transaction N servisi etkiliyor	⚠	Outbox + eventual consistency
Schema migration N repo PR	⚠	Contract versioning

3+ smell varsa → yanlış sınır, yeniden değerlendir.

Checklist

• Bounded context map (DDD)
• Extraction prioritization skor (≥ 24 ilk hedef)
• İlk hedef düşük risk (payments / core checkout değil)
• ADR Accepted
• Strangler Fig 5-6 phase plan
• ACL adapter implementation
• Consumer-driven contract (Pact)
• Operational readiness gate (10+ kalem)
• Database split prosedür (varsa)
• Saga / outbox distributed transaction
• 90 gün rollback window + feature flag
• Rollback drill ≥ 1
• Conway's law uyum (team boundary = service)
• Distributed monolith smell check

Antipattern

• Bounded context yok.
• Big-bang extraction.
• Shared DB sustained (distributed monolith).
• ACL yok.
• Contract test yok.
• Operational readiness yok.
• Rollback window yok.
• Distributed transaction tek DB bağlı.
• Sync call chain > 3 hop.
• Network partition unconsidered.
• Conway ihlal.
• "Modern" extraction değer kanıtsız.
• İlk extraction yüksek risk (payments / core).
• Schema migration N repo PR.

Örnek Agent Davranışı

User: /extract-service notifications
Agent (system-design-architect + migration-planner +
       architecture-decision-writer):

1. DDD bağı: notifications context bounded ✓ (publish event-driven,
   read-mostly aggregate, tek team owner).
2. Skor: deploy freq 5, compliance 2, scaling 4, team 5, coupling 5,
   risk 4 = 25 → adopt.
3. ADR yaz: notifications extraction (alternatif: kalsın monolith;
   konsekans: 1 ay sprint cost; team independent deploy +30%).
4. Strangler Fig 5-phase + 6 (DB split deferred).
5. ACL adapter LegacyNotificationAdapter.
6. Pact contract: web-frontend + mobile-app consumer.
7. Production-readiness 10 kalem (1 eksik: rollback drill — schedule).
8. Database: shared schema OK Phase 6'ya kadar.
9. Saga gerek YOK (notification side-effect, transaction yok).
10. 90 gün feature flag + canary.

Action items: 8 issue, ETA 4-5 hafta.

Çıktı Formatı

# Microservice Extraction: <context-name>

## Bounded Context Verification
- DDD model bağı + ubiquitous language

## Prioritization Score

## ADR
- Decision + alternatives + consequences

## Strangler Fig Phase Plan
- Phase 1-5 (+ 6 DB split varsa)
- Rollback per phase

## ACL Adapter

## Consumer-Driven Contract

## Operational Readiness Gate
- 10+ checklist

## Database Split (varsa)

## Distributed Transaction Strategy
- Saga / Outbox

## Distributed Monolith Smell Check

## Findings (Critical/High/Medium/Low)

## Action Items
| P | Aksiyon | Sahip | Bitiş | Issue |