adr.zone

ADR Example: Strangler-style monolith extraction (ISO 42010–inspired 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

Incremental extraction from the order monolith (2026 program)

Architecture description record (ISO/IEC/IEEE 42010–inspired). Lightweight, Git-friendly fields. Not a full conformance report to the standard—use the vocabulary of stakeholders, concerns, and views to align the decision with the architecture description.

Record ID (cross-ref): ADR-42010-0021

System / subject scope

order-api monolith, new edge services, shared MySQL during transition, OpenAPI-surfaced integration APIs.

Stakeholders and roles

Owning product teams, platform/SRE, security review for North/South routing.

Stakeholder concerns (to be addressed in the architecture description)

Deploy coupling, data ownership, incident blast radius, verifiable cutover, avoid repeating failed big-bang split.

View and viewpoint (what is shown, and from which perspective)

Viewpoint: integration and deployment. View: which paths are monolith-served vs service-served, and SLOs per public surface.

Decision

Adopt incremental strangler extraction: services own read models and contracts first; monolith remains write authority until bounded ADRs change that for each context. Shared database is an explicit transition state.

Rationale (with respect to the concerns and alternatives)

The architecture must stay honest about who writes which aggregate. A strangler with contracts and SLOs addresses coupling without pretending databases are already isolated. Phase-two physical split is gated on proven ownership in code and tests.

Architectural impact (elements, relationships, and operational follow-through)

New services must ship OpenAPI, ownership, and observability that spans async and sync paths. Gateway and threat model updates are mandatory when bypassing standard paths.

Traceability (requirements, policy, SLOs, other ADRs)

2024 post-mortem doc; 2026 program board; per-service ADR links as write path moves.