Choose a change the business can accept on its own
A billing application is expensive to change, and a team proposes replacing it one service at a time. The first candidate is invoice creation. Another is letting customers download an existing invoice. Both appear under billing in the navigation, but they carry different obligations. Creating an invoice determines amounts and issues a business record. Rendering a download can consume a record that already exists.
For this design exercise, choose the download path if invoice layout changes are a real delivery constraint. The desired outcome is that a team can change the renderer without releasing invoice creation. Assume the product permits regenerated downloads. If customers require the original signed or retained file, serving that artifact remains part of the contract and this rendering proposal needs a different scope.
Martin Fowler's Strangler Fig account describes identifying seams so that parts of a legacy system can be replaced independently. The first seam should support a useful outcome with a manageable set of dependencies. Its value must justify operating both implementations while the transition remains open.
Trace everyone who can produce the document
Start with a request from an authorized customer and follow it through invoice lookup, rendering, and delivery. Then locate other callers of the same behavior. A support console may generate a download directly. A monthly email job may call an internal rendering function. Moving the public endpoint alone leaves those callers on a different implementation.
Write down which entry points belong in the first slice. For each one, record who checks access, which invoice version it selects, and how it reaches the renderer. Keep excluded paths explicit, including their compatibility obligations. A team cannot retire an old function while a job still depends on it.
AWS's strangler guidance describes an adapter for legacy callers that must reach extracted functionality. That is useful here: the email job can keep its calling convention while an adapter supplies the replacement's input. Count this adapter as migration work, with a named owner and a condition for removal.
Give the renderer a complete, authoritative input
Keep invoice issuance and monetary calculations in the existing billing system for this slice. It supplies an immutable snapshot identified by account, invoice, and revision. The snapshot includes the issued amounts and currency, along with the customer details and line descriptions required for the document. The renderer must not reconstruct historical values from today's product catalogue or customer profile.
Specify the output separately: required fields must remain readable, totals must match the supplied record, and download behavior must remain compatible with existing clients. File names and content type may matter to integrations. Decide whether layout can change. Comparing PDF bytes is useful only when byte identity belongs to the requirement; a changed timestamp or font encoding can otherwise obscure a correct rendering.
The billing boundary must authorize the requested account and invoice before releasing its snapshot. A routing flag cannot confer that authority. Reject a snapshot with the wrong identity or an unsupported snapshot schema version instead of treating it as missing and fetching a different record. This prevents a convenient adapter from quietly choosing another meaning for the request.
- RequestAuthorize the invoice
Bind the customer request to its account, invoice, and permitted revision.
- SnapshotRead the issued record
Billing supplies historical amounts and document fields without recalculation.
- RouteSelect one renderer
The migration route chooses the old or new implementation under one output contract.
- DeliverReturn the download
Serve the compatible document and retain the selected renderer and snapshot identity in diagnostics.
Rehearse coexistence against the same snapshots
Create a small reference set before routing customers. Include an older invoice whose customer address has since changed, a long document that crosses page boundaries, and supported currencies with different formatting. Run both renderers against each identical snapshot. Check the required values in the rendered output and inspect readability where text extraction cannot establish it. Retain the inputs and expected outcomes so another engineer can repeat the comparison.
Exercise the paths that expose hidden ownership. A download must not update invoice totals or current customer details. The support console and email job must select the same invoice revision as the public route when asked for that revision. A request without access must receive no document through either implementation. An unsupported snapshot format must produce the agreed failure, without substituting current data.
Pause the replacement renderer during a rehearsal and observe the agreed failure behavior at every included entry point. Keep shadow output away from customers and email delivery. A comparison that sends a second message has introduced another business operation. These are proposed acceptance checks; their results must come from the actual implementation and its environment.
Make the transition an operating responsibility
Route a bounded customer cohort through the replacement and record which renderer served each request. Make that selection observable to support staff. Diagnose a failed download using its invoice snapshot identity and renderer release, while keeping invoice contents out of routine logs. Compare customer-visible failures and duration against the agreed operating limits.
Microsoft's Strangler Fig guidance warns that the facade can become a bottleneck or single point of failure. Include its failure behavior in the release rehearsal. Keep the old renderer supported for the planned coexistence period, and assign responsibility for changes to the shared snapshot contract. Independent releases still depend on compatibility at that interface.
The funding decision can now name a bounded deliverable: customer downloads use a replaceable renderer, invoice authority remains intact, and every included caller passes the coexistence checks. Before approving the next extraction, inspect what this slice actually removed from the old release process. Any remaining direct caller or shared calculation becomes evidence for the next boundary decision.
