sxsphinxstack

Skills / Advanced / Decompose a production monolith

Advanced Code skill

Decompose a production monolith

Decompose a production monolith through measured domain boundaries, dependency and data ownership, compatible extraction waves, parity tests, and rollback.

Change one verified ownership boundary at a time.

When to use

  • Use when the monolith's coupling creates demonstrated release, reliability, scaling, security, or team-ownership constraints.
  • Use modularization inside the monolith when network separation would add cost without a clear independently operated boundary.

Preconditions

  • Confirm business owners, architecture and operations authority, service objectives, release constraints, incident history, compliance, budget, and migration horizon.
  • Baseline runtime topology, request paths, dependencies, deployment, data, transactions, jobs, sessions, caches, reports, security, observability, and cost.
  • Freeze destructive architectural changes until rollback and data-ownership evidence exists.

Procedure

  1. Create a domain and dependency inventory of capabilities, code, owners, callers, data, transactions, events, jobs, reports, failure paths, and operational objectives.
  2. Measure change coupling, runtime traffic, latency, failure propagation, scaling pressure, release conflicts, and support load.
  3. Discover hidden transactions through database transaction traces, query and audit logs, stored procedures, triggers, lock analysis, request traces, and job causality before assigning boundaries.
  4. Choose a bounded extraction candidate with coherent business responsibility, enforceable interface, operational owner, and measurable benefit.
  5. Define data and transaction ownership for authoritative writes, reads, invariants, cross-boundary workflows, history, and reconciliation.
  6. Create an internal seam, compatibility facade, or anti-corruption layer before introducing a network boundary.
  7. Define versioned contracts, identity, authorization, idempotency, deadlines, retries, observability, and failure semantics.
  8. Establish data transition through expand, copy, verify, dual-read or controlled dual-write, ownership switch, and contraction without uncontrolled multi-writer state.
  9. Run extraction waves for shadow reads, low-risk consumers, bounded writes, jobs, reports, and critical flows with explicit gates.
  10. Verify behavior, data, permissions, latency, load, cost, failure isolation, recovery, and operational readiness at each wave.
  11. Rehearse rollback of routing and ownership without losing effects already committed across the boundary.
  12. Cut over under monitored decision authority and keep the original path available until reconciliation and recovery evidence stabilizes.
  13. Remove obsolete code, data paths, permissions, flags, and infrastructure only after consumers and retention duties are proven complete.

Failure plan

  • If an invariant still requires an undocumented cross-module transaction, stop extraction and model the workflow before splitting it.
  • If dual writes diverge, declare one authority, halt expansion, preserve both histories, and reconcile before retrying.
  • If latency, failure coupling, or operator burden worsens beyond the gate, route back while preserving committed business effects.
  • If a service has no accountable operations owner, do not create it.
  • Never use a new service boundary to bypass authorization, audit, privacy, or data-residency controls.

Worked example

A commerce monolith shares one database across checkout, inventory, billing, support, reporting, sessions, caches, and jobs. Teams want four services within six months, but cross-module transactions are undocumented. The program inventories runtime and data coupling, chooses notification history as a lower-risk first boundary, creates an internal interface, assigns authoritative data ownership, shadows reads, migrates jobs and consumers in waves, and rehearses routing rollback. Checkout remains inside until order and inventory invariants can be modeled and reconciled safely.

Related skills