Your Architecture Diagram Is Not a Modernization Plan

A modernization plan should not be approved because the workshop diagram looks coherent. Consider a hypothetical approval workflow: the team places approval rules in an Order service, but a code trace finds that a database trigger, a scheduled export and a manually maintained exception list also affect the outcome. The diagram may accurately describe the business’s intended process. It does not yet describe the system that must be changed.

A convincing model is a hypothesis about the system

A process workshop is useful. It gives people names for events, surfaces disagreements and makes proposed boundaries discussable. Its failure mode is subtler than drawing the wrong boxes: participants leave with a shared model and start treating it as an inventory of implementation work.

Those are different artifacts. “An order is approved after a credit check” describes an outcome. It does not tell you whether the decision happens in an API handler, a database function, a nightly job, an external provider or a person’s spreadsheet. It also says nothing about which component owns the authoritative status or what happens when two updates arrive close together.

Oskar Dudycz argues that a process model is an input to design, not its endpoint: proposed workflows and boundaries still need to be connected to the existing solution and code. That distinction should govern the funding decision. Approve discovery against the model before approving a target architecture based on it.

Do not throw the diagram away. Use it to decide what to inspect. Mark disagreements and uncertain assumptions as hot spots, then assign someone to resolve them rather than quietly choosing whichever account sounds most plausible. Dudycz’s guidance on hot spots makes that follow-up part of the workshop’s work, not an optional cleanup exercise.

Select workflows that can change the decision

A bounded assessment cannot read every module or prove that it has found every production path. Its value comes from choosing a small sample that tests the proposed architecture where a wrong assumption would matter.

Start with the decision the CTO needs to make. Is the question whether approvals can move into a new service? Whether the existing application can be stabilized instead? Whether an integration blocks a staged migration? Select two or three end-to-end workflows by business consequence and architectural contrast: a revenue-producing happy path, a denial or exception path, and a delayed batch or integration path. These are examples of selection criteria, not a universal list.

Trace each from the event that starts it to the outcome the user or another system sees. Resist the temptation to catalog every module. A module inventory can be extensive while still missing the one scheduled job that reverses yesterday’s apparent decision.

Bring the people who know different parts of that path into the assessment. Engineers can point to handlers and configuration; workflow owners can say whether an observed rule is intended; operations staff can identify retries, incidents and manual interventions. Users may reveal workarounds outside the application. The authors of Patterns of Legacy Displacement warn that discovery often stops at the legacy system’s boundary, even though the business process extends beyond it. That is exactly where a proposed replacement can acquire an unexpected dependency.

For each selected workflow, record the same fields: the business event and expected outcome; entry point; handlers and decision branches; authoritative data and database logic; background jobs and external calls; operational evidence; rule owner; source-file or trace reference; and unresolved question. This is a trace template, not a demand for exhaustive documentation. A blank field is useful when it shows what evidence is missing.

Follow the workflow past the boxes

Begin with the architecture diagram, then try to disprove it. AWS’s detailed application assessment guidance starts with a diagram but calls for validation against discovery data and monitoring. Its questions cover APIs, batch jobs, data flows, incidents, tests and operational dependencies. That is a better use of a diagram than accepting it as a map of everything that runs.

At the entry point, identify what calls the workflow and how it is identified across systems. Follow the code branches that choose outcomes, including authorization and exception handling. Then inspect the writes: which data is authoritative, which copy is derived, and which transaction must succeed as a unit? A proposed service boundary is not credible if it cuts across a transaction whose ownership nobody has examined.

Database logic deserves explicit attention. AWS identifies stored procedures, triggers and database functions as possible homes for validations, calculations, business rules and audit behavior, and advises mapping dependencies and transaction boundaries before moving that logic. In the hypothetical approval example, finding a trigger would not automatically mean “move the trigger into the Order service.” It would mean identifying what it enforces, what invokes it and what would break if its behavior changed.

Keep following the data after the immediate response. A scheduled export might determine what a partner treats as approved; a callback might update a status later; an exception list might override a result before anyone acts on it. The Revert to Source pattern recommends tracing important data flows to their origins and destinations beyond the legacy system because diagrams can hide integrations behind it.

Cross-check repository findings against tests, configuration and operational evidence where access allows. A branch in code establishes a possible path, not its production frequency or its business importance. A log entry establishes that something happened, not that it was correct. If traces, incident records or production access are unavailable, mark the resulting claim as provisional. Do not turn absence of evidence into evidence that a path is unused.

This is also where a proposed boundary can fail a narrower test. An approval rule that depends on authorization decisions across components may need to remain coordinated rather than being assigned to whichever new service has the most intuitive name. The same discipline of following a consequential rule through its actual enforcement points applies to auditing authorization before splitting services.

Turn disagreements into findings, not a cleaner diagram

When the model and implementation disagree, preserve the disagreement in a findings register. For each item, capture what the model says; what code or runtime evidence shows; the affected business outcome; confidence; who can resolve it; and which decision it blocks. Include references precise enough for another engineer to reproduce the finding.

For the hypothetical approval path, the register might say: “The workshop assigns approval to the Order service. A database trigger can reject the status update, and a later export changes what the partner sees. The manual exception process has not been verified.” The decision blocked is not necessarily the entire modernization. It might be the decision to extract approval without first defining ownership of status and exceptions.

Separate three questions that are often collapsed: What does the system do? Why does it do that? What should it do after modernization? A legacy rule may be an essential control, an accidental constraint or a workaround for a failure that no longer exists. Ask the workflow owner whether to preserve, deliberately change or investigate it before writing acceptance criteria. Otherwise, “match the old system” can silently become the product specification.

Sometimes localized parity is necessary. The Feature Parity pattern calls for examining user actions, batch work, interfaces, database behavior and reports when like-for-like replacement is required. Its authors also caution against making parity the goal for an entire legacy system. Scope parity to the outcome that actually needs it, rather than pricing a rebuild around every observed quirk.

State the assessment’s exclusions alongside its findings. Sampling workflows cannot establish that all dependencies have been found. Missing runtime access, unobserved seasonal paths and unresolved manual processes should remain visible, each with an owner or a reason to defer it. A polished diagram is no substitute for an honest confidence level.

Fund a first change, not an untested end-state

The assessment should offer choices, including keeping and improving the current system. An immediate risk may warrant a fix in place. Unclear behavior may warrant tests or observability before structural change. A verified boundary may justify a bounded pilot. Wider replacement should depend on what those steps reveal, not merely on the target diagram’s appeal.

A pilot needs a place to intervene. Martin Fowler’s description of a legacy seam is useful here: a seam lets you change behavior without editing code at that place. It can support observation, tests or gradual redirection, but finding or creating one may itself be substantial work. If there is no safe way to separate the workflow, fixing the existing implementation or doing more discovery may be the better first investment.

Define the pilot before approving it: the business outcome it must preserve or change, the data owner, compatibility requirements while old and new coexist, the operational signals to watch, a stop condition and a rollback route. Incremental replacement has real costs in routing, monitoring and data compatibility. AWS warns that a strangler-fig approach needs rollback and may not suit a system whose requests cannot be intercepted and routed. A plan that assumes interception without proving it is not staged; it is speculative.

Keep planned verification distinct from delivered results. In a Thoughtworks account of a mainframe assessment, the team tested business and technical boundaries to choose increments, but its planned dual-run comparisons were not production outcomes; the first year’s work did not go into production. That example is not a delivery benchmark. It is a reminder to label a pilot’s proposed checks as proposed until they have actually run.

An assessment deliverable should therefore be short enough to drive a decision: a diagnosis with reproducible evidence, viable options, a dependency-ordered roadmap, explicit exclusions and the decision to make after the pilot. It should not claim a complete migration estimate from a few traced workflows. An evidence-backed code audit and technical assessment is useful when the organization needs that diagnosis before committing to a modernization path.

A funding checklist for the CTO

Before approving the next stage, ask the team to show:

• Selection: Which consequential workflows were traced, and which paths were deliberately left out?

• Evidence: Can another engineer follow each key finding from the process model to code, data, integration or operational evidence?

• Disagreements: Which proposed boundaries conflict with observed behavior, who owns each unresolved question, and what decision does it block?

• Intent: Which legacy behaviors must be preserved, which should change, and which still need a business decision?

• Options: What can be fixed in place, what needs more observation, and what bounded change has a credible seam?

• Pilot control: What outcome, data compatibility, monitoring, stop condition and rollback will determine whether to expand?

If those answers are weak, fund the missing investigation rather than the target architecture. If they are strong, approve the smallest change that can test the plan—and make the next funding decision depend on what that change proves.