A useful monolith-to-microservices migration diagram does more than show boxes and arrows: it makes ownership, dependencies, traffic, data movement, and rollback decisions visible. This checklist explains how to map the current system, choose service boundaries, illustrate an incremental strangler migration, and review each extraction before production cutover.
Overview
Start with a current-state monolith decomposition diagram, not a desired end state. The first diagram should describe how the system behaves today, including application modules, external clients, scheduled jobs, databases, queues, third-party APIs, and operational dependencies. If a dependency is important to reliability, security, or data correctness, it belongs on the map even if it is not part of the application code.
Then create a future-state monolith-to-microservices diagram that shows only the boundaries you have evidence to support. Avoid drawing every possible service. A smaller number of well-understood extraction candidates is more useful than a polished but speculative target architecture.
A practical migration diagram normally includes three views:
- System context: users, clients, external systems, and the monolith as a whole.
- Container or component view: business capabilities, internal modules, data stores, and synchronous or asynchronous calls.
- Transition view: routes that have moved, routes still handled by the monolith, temporary adapters, shared data access, and rollback paths.
A C4-style set of views can help keep these levels separate; see the C4 model diagram guide for a practical way to organize context, container, component, and code views. For migration work, the transition view is especially important because it documents the architecture that exists between the starting point and the destination.
Checklist by scenario
1. Mapping the current monolith
- List the major business capabilities, such as ordering, billing, identity, fulfillment, or reporting.
- Map which modules, packages, or teams implement each capability.
- Show inbound traffic from web clients, mobile clients, internal consumers, and scheduled processes.
- Trace calls between modules, including direct database reads, shared libraries, synchronous APIs, queues, and batch jobs.
- Mark databases, tables, caches, object storage, and search indexes that each capability reads or writes.
- Label relationships as synchronous, asynchronous, read-only, write, event-driven, or unknown.
Do not infer boundaries from folder names alone. A module called “payments” may still depend on customer, order, tax, and reporting tables. Confirm the runtime and data relationships with code search, logs, query traces, deployment configuration, and conversations with the teams that operate the system.
2. Identifying candidate service boundaries
Use business capability and data ownership as the primary boundary criteria. A candidate service should have a clear purpose, an accountable owner, a coherent set of workflows, and a manageable set of dependencies. Consider these questions:
- Can the capability be described without referring to several unrelated domains?
- Does one team understand and operate most of its behavior?
- Can its data ownership be stated in concrete terms?
- Are its consistency requirements compatible with an independent deployment?
- Would extracting it reduce a meaningful delivery, scaling, reliability, or ownership problem?
- Can the team introduce an API or event contract without exposing internal tables?
Capture the reasoning in an architecture decision record and link it to the diagram. The architecture decision record diagram guide can help connect a boundary choice to its tradeoffs rather than presenting the choice as self-evident.
3. Showing the strangler pattern
For an incremental migration, draw the new service beside the monolith and show the routing layer in front of both. Use distinct line styles or colors with a legend:
- Solid arrows: production traffic currently handled by the component.
- Dashed arrows: planned routes or temporary compatibility calls.
- Red or warning styling: shared databases, fragile coupling, or unverified dependencies.
- Numbered markers: extraction steps, such as introduce route, backfill data, dual-read, cut over, and remove legacy code.
A useful transition diagram shows what happens to an individual request. For example: client to gateway, gateway to the new Catalog service for migrated endpoints, Catalog service to its owned store, and the remaining endpoints to the monolith. If the new service calls the monolith for information, show that dependency explicitly rather than implying independence.
4. Tracing database ownership
Place data stores directly on the architecture diagram and label every access path. A temporary shared database is not automatically a failure, but it should be visible as a migration constraint. Identify whether the plan uses a separate schema, a new database, replication, change data capture, an outbox, an anti-corruption layer, or a scheduled backfill.
Use an ERD alongside the architecture view when table relationships are central to the extraction. The database schema diagram guide covers how to make ownership and relationships easier to inspect.
5. Comparing boundary options
| Boundary signal | What the diagram should show | Review question |
|---|---|---|
| Business capability | Workflow, owner, inputs, outputs, and related modules | Does the service have one coherent purpose? |
| Data ownership | Authoritative store and all temporary access paths | Can other components stop writing its tables? |
| Team ownership | Maintaining team and operational responsibility | Can one team change and support it safely? |
| Runtime coupling | Call direction, latency-sensitive paths, and failure behavior | What happens when the dependency is unavailable? |
| Migration value | Problem addressed by extraction and measurable outcome | Is the complexity justified by a real constraint? |
What to double-check
Before approving an extraction, review the diagram with developers, operators, security stakeholders, and the people who understand the business workflow. Use this migration review checklist:
- Shared database: Are shared tables, cross-service joins, triggers, stored procedures, and migration locks identified?
- Synchronous coupling: Are timeout, retry, circuit-breaker, and partial-failure behaviors documented for every important call?
- Data ownership: Is there one authoritative writer for each migrated business object? If not, what is the temporary reconciliation rule?
- Consistency: Can the workflow tolerate eventual consistency, or does it need a process manager, reservation, or compensating action?
- Rollback: Can traffic return to the monolith without losing writes or producing duplicate side effects?
- Observability: Do logs, metrics, traces, correlation IDs, business outcomes, and alerts cross the old and new paths?
- Security: Are authentication, authorization, secrets, network boundaries, and sensitive data flows represented?
- Operations: Is ownership clear for deployment, on-call response, capacity, backups, and incident handling?
Keep the diagram close to the implementation. Store source files with the repository or documentation workflow, review visual changes with code changes, and record the date or migration milestone represented. The guide to diagram version control offers a useful review model for teams that treat architecture visuals as maintainable engineering artifacts.
Common mistakes
- Drawing the destination as if it already exists. A future-state diagram cannot guide a cutover unless the transitional dependencies are visible.
- Using arrows without semantics. An arrow should indicate a call, event, data read, data write, or route. Add a legend and avoid ambiguous lines.
- Splitting by technical layer. Services organized only as “API,” “business logic,” and “database” often preserve the same coupling under new names. Begin with business capabilities and ownership.
- Ignoring background work. Cron jobs, workers, exports, reconciliation tasks, and administrative scripts frequently write the same data as the main application.
- Hiding temporary designs. Adapters, dual writes, shared schemas, and monolith callbacks may be acceptable steps, but hiding them makes risk impossible to review.
- Making one overloaded diagram. Separate context, runtime flow, data ownership, deployment, and migration sequence into focused views. Link them with consistent names.
- Confusing extraction with improvement. Moving code to a new process does not automatically improve reliability or ownership. Define the problem the extraction is meant to solve.
When to revisit
Treat the monolith decomposition diagram as a living migration record. Revisit it before each planning cycle, before selecting the next extraction seam, and whenever the underlying system changes. Update it after a database split, route cutover, ownership change, new event flow, incident, or rollback.
At every milestone, compare the diagram with production reality. Remove temporary arrows only after the corresponding dependency has actually been retired. Add a visible status to each candidate boundary: proposed, in discovery, in migration, cut over, stabilizing, or complete. This keeps planning conversations grounded in what exists rather than what was intended.
When workflows or diagramming tools change, preserve the same information even if the notation changes. A browser-based diagram maker, a diagram-as-code workflow, or an embedded documentation view can all work if the source is reviewable, the legend is clear, and revisions are traceable. For related infrastructure context, connect this work with network architecture diagrams, Kubernetes architecture diagrams, and event-driven architecture diagrams.
Action for the next review: choose one candidate capability, produce a current-state view, trace its database access and runtime dependencies, draw the smallest safe extraction, and ask reviewers to challenge the rollback and observability paths. That focused exercise usually reveals more than a broad target diagram and gives the team a concrete basis for the next migration step.