Why Monolith Migrations Go Wrong
Having spent years wiring together Node.js services behind an Express gateway — and having watched PM2 restart loops cascade through a poorly decoupled architecture — I have a healthy respect for how hard it is to break up a monolith without breaking the business that runs on it. This post is a migration playbook: the sequence of architectural, tooling, and cultural moves that make a monolith-to-microservices transition survivable. It is a synthesis of patterns that are well documented across the industry and that I apply, at a smaller scale, in my own systems.
The typical starting point looks like this: an application that has grown for a decade, where every feature lives in one codebase, a single change requires a full regression cycle, and deployments are coordinated, high-stress events. The pain is real, but the biggest mistake teams make is treating it as a purely technical problem. It rarely is.
The Real Costs of Staying Put
Before committing to a migration, it is worth being precise about what the monolith is actually costing you, because a migration done for fashion reasons will fail. The recurring costs that justify the effort are:
- Deployment fear: When releases are large and infrequent, the risk of each one is high. Teams respond by releasing even less often, which makes each release bigger and riskier — a self-reinforcing freeze.
- Scaling inefficiency: If one hot module forces you to scale the entire application horizontally, you pay to replicate code that is idle. Coarse-grained scaling wastes a large share of the infrastructure budget.
- Configuration drift: Hand-provisioned servers diverge over time, so staging stops resembling production and every deployment becomes an experiment.
If none of these are biting you, a well-factored monolith with a good pipeline may serve you better than a distributed system. Microservices are a trade: you exchange deployment coupling for network complexity, and the exchange only pays off past a certain scale of team and traffic.
Phase 1: Fix the Team Boundaries Before the Service Boundaries
Organizational bottlenecks almost always precede technical ones. The classic failure mode is the “Wall of Confusion”: developers optimizing for change, operations optimizing for stability, and code thrown over the fence between them with no shared context.
The structural fix is cross-functional squads owning business domains — payments, identity, notifications — rather than teams organized by technology layer. Each squad includes the people needed to build and run its services, following the “you build it, you run it” principle. Two practical notes from teams that have done this:
- Moving from time-boxed sprints to a Kanban-style flow with explicit WIP limits tends to suit migration work better, because migration tasks are irregular in size and constant re-estimation becomes ceremony.
- Squad boundaries are a first draft of your service boundaries. If two squads cannot agree where a responsibility lives, that ambiguity will resurface later as a tangled API between their services.
Phase 2: Strangle, Don’t Rewrite
The single most important technical decision is to reject the big-bang rewrite. The Strangler Fig pattern — routing specific functionality to new services while the legacy monolith continues handling everything else — lets you migrate incrementally, validate each step in production, and retreat cheaply when a boundary turns out to be wrong.
Choose the first candidate deliberately: a module that is volatile (changes often, so the payoff is immediate) but well-bounded (its data and logic separate cleanly). A currency-conversion engine, a notification sender, or a search endpoint are typical first cuts. Your most entangled core domain should be last, not first.
Containerize for Immutability, Not Portability
Docker‘s practical value in a migration is not portability — it is that a container image is an immutable artifact. The exact binary that passed tests in CI is what runs in production, which eliminates an entire class of environment-related failures. A multi-stage build for a TypeScript service keeps the production image lean:
# currency-conversion/Dockerfile
FROM node:20.11-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npx tsc --project tsconfig.json
# --- Production image ---
FROM node:20.11-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package.json ./
EXPOSE 3000
CMD ["node", "dist/index.js"]
The final image contains no TypeScript compiler, no source files, and no devDependencies — only compiled output and production modules. Smaller surface, faster pulls, less for a vulnerability scanner to complain about.
The Architectural Ground Rules
- API first: All inter-service communication goes through documented interfaces (REST or gRPC). If a service reads another service’s database directly, you have built a distributed monolith.
- Database per service: Each service owns its data — PostgreSQL for transactional records, Redis for caching and ephemeral state, a document store where the shape genuinely varies. You lose the convenience of a cross-domain
JOIN; you gain the ability to deploy and scale services independently, which is the entire point. - Design for failure: The network between your services will fail. Timeouts, retries with backoff, and circuit breakers are not optional extras; they are the cost of admission.
Phase 3: The Pipeline That Makes It Safe
Extracting services without automating delivery just multiplies your deployment problems by the number of services. Three pipeline practices carry most of the weight:
Trunk-based development. Small, frequent merges to the main branch, validated by automated tests on every push. Long-lived feature branches reintroduce the integration pain the migration was meant to remove.
Infrastructure as Code. Defining environments in Terraform (or an equivalent) makes infrastructure auditable: every change is a pull request, a new staging environment is an apply rather than a ticket, and a misconfigured security group is a visible diff instead of a mystery found during an incident review.
Progressive rollout. For zero-downtime requirements, Blue/Green deployments spin the new version up alongside the old and shift traffic only after health checks pass — rollback is a load-balancer rule change, effectively instantaneous. Canary releases go further: route a small slice of traffic (say 5%) to the new version and promote automatically only if error rates stay flat. Canaries catch the failures that only appear under real production traffic, which staging never fully reproduces.
Phase 4: Observability Is Not Optional
In a distributed system you cannot SSH into “the server” and read “the log”. Before decomposing anything, put in place:
- Centralized, structured logging with correlation IDs propagated across service calls — debugging a request that crosses five services without them is misery.
- Metrics and alerting (Prometheus and Grafana are the default stack) with Service Level Objectives defined on user-facing flows. Tracking p99 latency on the checkout path tells you what a blunt uptime percentage hides: a service can be “up” while being unusably slow for one user in a hundred.
- Security scanning in CI: dependency and container scanning (Snyk, Trivy) on every pull request, so a known-critical CVE cannot be promoted to production.
How to Judge Whether It Is Working
Resist vanity metrics. The four DORA measures are the honest scoreboard for a migration like this: deployment frequency, lead time for changes, mean time to recovery, and change failure rate. Teams that complete this kind of transition typically move from quarterly releases to on-demand deploys, and from recovery measured in hours to minutes — but measure your own baseline before you start, or you will never know whether the complexity you took on actually bought you anything.
Where to Start
- Start small: One well-bounded, non-critical service as the pilot. The Strangler Fig pattern exists precisely to make the first step low-risk.
- Automate the pain first: Any manual step you repeat more than twice — environment setup, deployment, certificate renewal — is a reliability incident waiting to happen.
- Observability before decomposition: Centralized logging and tracing must exist before the second service does.
- Security left, not last: Scanning on every pull request costs almost nothing and catches issues when they are cheapest to fix.
A monolith-to-microservices migration is not primarily about Kubernetes or Terraform — it is about connecting culture, architecture, delivery, and operations into one coherent system. The principles above apply whether you are running a single Express API on a VPS or dozens of services across a cloud provider: identify your biggest bottleneck — deployment fear, configuration drift, or lack of visibility — and fix that one first.
