adr.zone

ADR Example: Strangler-style monolith extraction (Outcome-First format)

Example ADR for decomposing a live monolith without a big-bang: strangler patterns, who owns the write path, and what is explicitly out of scope. The body below is the same decision rendered in the format you choose—use the toggle to compare how each template surfaces risks and follow-ups.

When this type of decision shows up

  • You are peeling off read-heavy or integration edges before touching the core write model.
  • You need a single-writer rule per aggregate while multiple services still touch a shared database during transition.
  • A prior “split the repo” attempt failed; you are encoding a different cutover and rollback story.

Format

Preview

ADR-0021: Incremental extraction from the order monolith

Status

Accepted

Outcome

Reduce release coupling and blast radius around order integrations without risking another big-bang rewrite.

Decision

Adopt a strangler approach: extract read-heavy reporting and external/partner API edges first, while keeping writes to core order state in the monolith until each write path is moved by a follow-up ADR.

Primary tradeoff

We accept a transitional architecture with shared MySQL tables and two deployment models, in exchange for safer incremental extraction.

Why

  • The order-api monolith still owns order lifecycle, pricing, and fulfillment
  • In-repo modularization helped, but deploys are still coupled
  • Promotions can still block shipment hotfixes
  • A 2024 big-bang split failed without a strangler path

Decision boundaries

Impacted:

  • Read-heavy reporting surfaces
  • External and partner API edges
  • SLOs, ownership, API contracts, and rollback rules for extracted services

Not impacted:

  • Core order write ownership
  • Business-rule language/runtime
  • Event sourcing adoption
  • Physical database separation before ownership boundaries are proven

Assumptions:

  • Shared MySQL remains acceptable during the transition
  • Core order state remains owned by the monolith until write ownership is explicitly moved
  • Integration tests can prove ownership boundaries before physical database splits

Guardrails:

  • Each extraction must include a versioned OpenAPI contract
  • Each extracted surface must have a CODEOWNERS owner
  • Each extracted surface must define SLOs outside the monolith release train
  • Rollback must not require coordinated DB migration on deploy day
  • Moving write ownership requires a follow-up ADR per bounded context