adr.zone

ADR Example: Strangler-style monolith extraction (Nygard ADR 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 (2026 program)

Status

Accepted

Context

The order-api monolith is still the system of record for order lifecycle, pricing, and fulfillment. Modularization in-repo helped, but deploys are coupled; promotions can still block shipment hotfixes.

We will extract read-heavy reporting and integration edges first, not “microservice everything” at once. Data ownership is messy: several tables are written by jobs and online traffic; cutover needs a single writer per aggregate to avoid split-brain.

A 2024 big-bang split failed without a strangler. This ADR: thin edge services, shared database during transition, physical split only after boundaries are proven in code and tests.

Decision

Adopt a strangler: new external and partner APIs ship from services that own their read models. Writes to core order state stay in the monolith until a follow-up ADR per context moves the write path.

Each extraction includes versioned OpenAPI, CODEOWNERS owner, SLOs outside the monolith release train, and a rollback that does not require a coordinated DB migration on the deploy day.

Shared MySQL remains during transition; per-service physical databases are phase two after write ownership is enforced in application code and integration tests prove it.

Consequences

Positive: integration endpoints can ship on smaller blast radius; autoscale applies per surface; fewer release coordination walls on read/async paths.

Negative: two deployment models in parallel increase platform work; shared tables need strict review of cross-table work in new service code; logging correlation is harder without discipline.

Non-goals: big-bang rewrites, new language for business rules, or mandated event sourcing in 2026 unless a separate ADR lands.

Follow-up: public migration board; North/South traffic must use the gateway and update threat model when it does not.