Software-Architecture on Corebaseit — Design System Engineering · POS · Payments · Security

From Monolith to Microservices: Architecture Is the Destination, Migration Is the Plan

contact@corebaseit.com (Vincent Bevia) — Thu, 27 Aug 2026 00:00:00 +0200

A monolith can become difficult to change long before it becomes impossible to run.

Deployments start affecting unrelated areas. A change in refunds requires regression testing checkout. One database becomes the integration layer between half the system. Teams wait for each other. Releases grow larger, rollback becomes scarier, and nobody is completely sure where one business capability ends and another begins.

At that point, somebody usually draws this:

The destination looks simple.

The migration is not.

Moving from a monolithic architecture to microservices is not primarily a matter of creating smaller applications. It is a controlled transfer of responsibility across boundaries while the existing system continues serving production traffic.

That makes it both an architectural problem and a project-management problem.

A useful migration therefore needs more than a target architecture.

It needs a path.

Start with the reason, not microservices

Before decomposing anything, ask a more uncomfortable question:

What problem are we actually trying to solve?

Microservices introduce their own costs: network failures, distributed tracing, eventual consistency, deployment coordination, infrastructure overhead, data ownership problems, versioned contracts, retries, duplicate messages, and substantially more operational surface area.

If the real problem is simply poor module boundaries inside the codebase, a modular monolith may be the better answer.

A migration should therefore start with measurable architectural drivers:

independent deployment of high-change capabilities;
different scaling characteristics;
clearer team ownership;
fault isolation;
regulatory or security boundaries;
independent technology evolution;
reducing coupling around specific business capabilities.

This is where the previous discussion about Spikes and ADRs becomes useful.

A Spike can investigate whether extracting a capability actually improves the characteristics we care about.

An ADR can record why that boundary was selected and which consequences were knowingly accepted.

The ADR tells us why.

The migration plan tells us how and when.

Those are different artifacts.

Do not migrate the monolith. Migrate a capability.

Imagine a payment platform containing:

A dangerous project starts with:

We are migrating the monolith to microservices.

That scope is enormous and gives the programme very few meaningful intermediate success states.

A better question is:

Which capability should we extract first?

Suppose Refunds is selected because it has clear business semantics, changes frequently, integrates with unreliable external providers, and has different scaling and failure characteristics from checkout.

Now the project becomes much more concrete:

That is something architecture and delivery teams can actually manage.

The target architecture is not the migration architecture

This distinction is easy to miss.

The desired end state might be:

But production cannot teleport from the current state to that diagram.

For some period of time, the real architecture will look more like this:

That intermediate state may live for weeks or months.

It is not temporary clutter to ignore.

It is the production architecture during the migration.

And it needs to be designed.

The Strangler Fig pattern

One of the best-known approaches to incremental replacement is Martin Fowler’s Strangler Fig Application pattern.

Instead of rewriting the entire system and switching everything at once, new functionality gradually grows around the old system.

Conceptually:

But the percentages are less important than the principle:

Replace capabilities incrementally while keeping the system operational.

This creates something extremely valuable in architecture programmes:

reversibility.

If the first extraction performs badly, creates unexpected coupling, or proves operationally expensive, the organisation has learned something without betting the entire platform.

That is architecture behaving like risk management.

Migration needs phases

Large architectural initiatives become much easier to reason about when separated into explicit phases.

A practical structure might look like this:

Phase 1 — Discovery

Understand why the capability is being extracted.

Map dependencies.

Identify database tables, APIs, scheduled jobs, events, operational dashboards, external integrations, and other modules that depend on it.

Run Spikes where uncertainty is material.

Produce ADRs for significant decisions.

The output is not yet a microservice.

It is reduced uncertainty.

Phase 2 — Establish the boundary

Define what the new service owns.

For Refunds, that might mean:

Refund Service owns:

- refund lifecycle
- refund state machine
- idempotency
- provider interaction
- retry policy
- refund persistence
- refund events

The boundary matters more than the framework.

A Spring Boot service with the wrong business boundary is still the wrong architecture.

Phase 3 — Build alongside the monolith

Do not immediately remove the existing path.

Create the new service while production continues through the monolith.

This gives the team somewhere to migrate traffic gradually.

Phase 4 — Validate in parallel

Before trusting the new path with all production traffic, compare behaviour.

Depending on the capability, techniques can include:

The second path does not necessarily execute external side effects. For payments and refunds, blindly duplicating a production command would obviously be dangerous.

But calculations, transformations, routing decisions, or state transitions can often be compared safely.

This turns migration from:

We think the new service works.

into:

Across 1.8 million representative operations, the old and new implementations agreed in 99.99% of the cases, and we understand the remaining differences.

That is a much stronger basis for moving traffic.

Move traffic, not hope

Eventually the new service must become authoritative.

Do not think only in terms of deployment.

Think in terms of traffic migration.

A migration might progress through controlled stages:

Stage 1 100% old 0% new
Stage 2 95% old 5% new
Stage 3 75% old 25% new
Stage 4 25% old 75% new
Stage 5 0% old 100% new

The exact percentages are implementation details.

The important part is that each stage has entry criteria, observations, and rollback conditions.

For example:

Proceed if:

error rate < threshold
p95 latency < threshold
duplicate rate = expected
reconciliation = clean
DLQ growth = normal
provider errors = understood

Architecture has now become measurable.

Data is usually the hard part

Extracting Java or TypeScript code into another repository is rarely the hardest part.

Data ownership is.

The monolith may currently do this:

Creating four services that all continue directly accessing those same tables gives us:

We have distributed the applications while preserving much of the original coupling.

This is sometimes a valid transitional state.

It is a poor place to stop accidentally.

A stronger destination is explicit ownership:

Now another problem appears.

A database transaction can no longer quietly coordinate everything.

Distributed boundaries force previously hidden architectural questions into the open:

What is the source of truth?
Which service owns the state transition?
What happens when a downstream call fails?
Do we need eventual consistency?
What is retried?
What must be idempotent?
What happens if an event is delivered twice?
How do we reconcile inconsistent states?

Microservices do not eliminate complexity.

They move complexity across boundaries.

Project management has to follow the architecture

Traditional project plans often describe migration in technical tasks:

Create repository
Create service
Create database
Implement endpoints
Deploy service

All of those tasks can be completed while the migration itself remains nowhere near finished.

A more meaningful plan tracks capability ownership.

For example:

Refund Extraction

[✓] Boundary agreed
[✓] ADRs accepted
[✓] Service operational
[✓] Observability available
[✓] Data ownership established
[✓] Shadow validation passed
[✓] 5% production traffic
[✓] 25% production traffic
[ ] 100% production traffic
[ ] Old refund path disabled
[ ] Old database access removed
[ ] Dead code removed

This changes what “done” means.

The service existing is not the milestone.

The responsibility having moved is.

Every migration step needs an exit condition

One of the most useful disciplines in architecture programmes is defining what allows the team to move to the next phase.

Without exit criteria, migrations tend to move according to calendar pressure:

We planned to switch on Thursday.

With exit criteria, the decision becomes evidence-based:

Error rate, latency and reconciliation are inside the agreed thresholds, so we can increase traffic.

That is a very different engineering culture.

Observability is part of the migration architecture

A migration without observability is extremely difficult to control.

Before moving production traffic, the new boundary should expose enough information to answer:

Is it working?
Is it slower?
Is it failing differently?
Are retries increasing?
Are duplicate requests appearing?
Where is time being spent?
Can we correlate the request across systems?

That means metrics, logs, and distributed traces are not something to “add later.”

They are part of the migration mechanism.

During the transition, a trace may cross both worlds:

Without correlation across that boundary, operational complexity increases precisely when the architecture is already at its most complicated.

Decommissioning is part of the project

Migration projects have a dangerous moment:

New service works.
Production uses it.
Everyone celebrates.

But the old implementation remains.

Six months later:

Refund Service
 +
Old Refund Module
 +
Old Tables
 +
Old Jobs
 +
Compatibility Code
 +
Temporary Routing

The organisation now owns more architecture than before the migration.

Decommissioning therefore belongs in the original plan.

Deleting the old architecture is not cleanup.

It is the final migration phase.

Architecture and project management meet in the middle

A system architect can draw an excellent target:

A project manager can build an excellent roadmap:

Q1 → Q2 → Q3 → Q4

Neither is sufficient alone.

The useful artifact connects them:

This is where architecture stops being a picture of the future and becomes an executable strategy.

The migration itself is architecture

There are really three architectures involved:

CURRENT STATE
 │
 ▼
TRANSITION ARCHITECTURE
 │
 ▼
TARGET STATE

Teams naturally spend most of their design effort on the first and third.

The middle deserves just as much attention.

During migration, the organisation may temporarily operate duplicate paths, compatibility APIs, routing rules, event bridges, shared databases, shadow traffic, feature flags, and synchronization mechanisms.

Those components may never appear in the final diagram.

They still need architecture decisions, ownership, observability, security, testing, and explicit retirement plans.

That is why a large architectural migration is not simply a refactoring exercise.

It is the controlled evolution of a running system.

A useful mental model

The entire approach can be reduced to:

Or even more compactly:

Architecture defines the destination. Migration architecture defines the safe path. Project management makes that path executable.

A monolith does not become a healthy microservice architecture because enough services were created.

The migration succeeds when responsibilities, data ownership, traffic, operational ownership, and failure handling have moved deliberately — and the old architecture can finally be deleted.

That is a much more meaningful definition of done.

References

Fowler, M. — Strangler Fig Application. MartinFowler.com.
Newman, S. — Monolith to Microservices: Evolutionary Patterns to Transform Your Monolith. O’Reilly Media.
Newman, S. — Building Microservices, 2nd Edition. O’Reilly Media.
Ford, N., Richards, M., Sadalage, P. & Dehghani, Z. — Software Architecture: The Hard Parts. O’Reilly Media.
Richards, M. & Ford, N. — Fundamentals of Software Architecture: An Engineering Approach. O’Reilly Media.
Nygard, M. — “Documenting Architecture Decisions.”
Fowler, M. — Feature Toggles (aka Feature Flags).
Corebaseit — Spike First, ADR Second: Evidence and Rationale in System Design.

Spike First, ADR Second: Evidence and Rationale in System Design

contact@corebaseit.com (Vincent Bevia) — Mon, 24 Aug 2026 00:00:00 +0200

System design discussions often collapse into technology comparisons: Kafka or SQS, PostgreSQL or DynamoDB, synchronous or asynchronous, monolith or microservices. Those choices matter. They are not the whole problem.

Architectural work has two other obligations that diagrams do not carry by themselves:

How did the team gather enough evidence to decide?
Why was this option chosen over the alternatives that were still on the table?

Two lightweight practices address those obligations: Spikes and Architecture Decision Records (ADRs). They solve different problems. Used together under uncertainty, they form a simple decision loop — investigate, decide, document — that keeps future teams from treating intentional trade-offs as accidents.

This post defines each practice, shows how they connect, and grounds the pattern in a payment-system example: asynchronous refund processing with external partner latency, retries, and idempotency. The POS framing draws on POINT OF SALE ARCHITECTURE (the book), especially Chapter 6 (architectural principles and separation of concerns), Chapter 14 (offline / store-and-forward queues, retries, idempotency), and Chapter 15 (backend timeouts, safe retries, STAN/RRN correlation).

Claims to keep separate

Confirmed practice and sources:

An ADR is a short record of an architecturally significant decision, typically covering context, decision, and consequences (Michael Nygard, 2011; Thoughtworks Technology Radar — Lightweight Architecture Decision Records).
A Spike (from Extreme Programming) is a time-boxed investigation used to reduce technical uncertainty before committing to an implementation path.
Payment backends that retry across unreliable partners must assume duplicate delivery and enforce idempotency; store-and-forward and authorization retries make this explicit (the book, Ch. 14–15).
Architecture is largely trade-off analysis among competing characteristics, not selection of a universally “best” technology (Richards & Ford, Fundamentals of Software Architecture).

Interpretation (practitioner method):

“Spike first, ADR second” is a useful default under uncertainty. It is not a rule that every ADR requires a Spike, or that every Spike must produce an ADR.
The refund / SQS example below is illustrative. Your broker, ordering needs, and partner SLAs will differ; the method transfers, the product choice may not.

Architecture contains uncertainty

Consider a refund processing path where an external GDS or airline API can be slow or temporarily unavailable:

Asynchronous processing is a reasonable starting assumption: the external system should not block the merchant-facing API indefinitely. That assumption does not answer the next layer of questions:

Managed queue (for example SQS) or log-oriented broker (for example Kafka)?
What ordering guarantees are actually required — global, per refund, or none?
Can messages be delivered more than once?
How do retries, dead-letter queues, and worker crashes interact?
Is replay a real requirement for this workflow, or only an attractive feature?
What throughput and latency budget does the partner path impose?

Drawing another box on the diagram papers over those unknowns. Naming the unknowns is more useful: the team does not know yet. That is the entry condition for a Spike.

In POS systems the same pattern appears whenever the stack sits between a deterministic payment state machine and an unreliable upstream — store-and-forward sync, scheme timeouts, late issuer responses, and duplicate suppression via STAN/RRN or dedicated idempotency keys (the book, Ch. 14–15; see also double charging).

Spike: reduce uncertainty before committing

A Spike is a time-boxed technical investigation aimed at a specific question. It is not the production implementation. It may include a small proof of concept, a benchmark, an integration test against a partner sandbox, latency or throughput measurement, or structured comparison of two or three alternatives.

The Spike starts with a question, for example:

Can a managed FIFO/work-queue service meet the ordering, retry, and throughput requirements of our refund processing path, if consumers are designed for at-least-once delivery?

Give the investigation a hard time box (often one to three days). Structure the work so findings are reusable:

A useful Spike ends with evidence, not preference. Typical findings for this kind of path:

Throughput is adequate for projected refund volume.
Ordering is required only per refund identifier, not globally.
Duplicate delivery must be assumed; workers need idempotent handlers.
Retries plus a dead-letter path cover the partner failure modes in scope.
Log replay is attractive but unnecessary for this workflow’s recovery model.

The decision can now rest on measured constraints. Months later, though, someone will still ask why the queue technology is what it is. Evidence that lived only in a chat thread or a demo branch will be gone. That is the ADR’s job.

ADR: preserve the reasoning behind the decision

An Architecture Decision Record is a short document that records one architecturally significant decision and the forces around it. Nygard’s original shape is Status, Context, Decision, and Consequences. Many teams add Alternatives Considered; that extension is useful in payment systems where several brokers or sync models are always in play.

A lightweight example:

ADR-017: Use a managed work queue for refund processing

Status
Accepted

Context
Refund processing is asynchronous. The external GDS can be slow or
unavailable. Workers can crash mid-flight. At-least-once delivery
must be assumed; duplicate refund side effects are unacceptable.

Decision
Use a managed work queue (SQS-class) for refund jobs, with
idempotent consumers keyed by refund id (and STAN/RRN where the
payment network is involved).

Alternatives considered
- Log-oriented broker (Kafka-class) for replay-first design
- Self-managed broker (RabbitMQ-class)
- Synchronous refund calls from the API

Consequences
+ Managed operations and built-in retry / DLQ patterns
+ Simple worker model aligned to job processing
- Consumers must be idempotent under duplicate delivery
- Weaker fit if full event replay becomes a primary requirement

The decision line alone is cheap; the architecture diagram already shows the queue. The durable value is context, alternatives, and accepted downsides. Without that, a later engineer can “fix” an intentional trade-off — for example by introducing a replay-heavy broker when the original Spike showed replay was out of scope.

Spike + ADR as a loop

Compact form:

Spike = investigate.
ADR = decide and document.

A Spike does not always produce an ADR. An ADR does not always require a Spike. Some decisions are constrained enough that experimentation would waste calendar time. When uncertainty is material — partner behaviour, ordering, duplicate risk, certification impact — the combination is hard to beat on cost relative to the confusion it prevents.

Why diagrams are not enough

System diagrams show what exists:

API → queue → workers → PostgreSQL / partner API

They do not naturally show why it exists: why this broker, why asynchronous rather than synchronous, why pessimistic rather than optimistic concurrency, why REST rather than an event bus for a given boundary.

A working architecture therefore has a second layer behind the boxes:

In POS application design, Chapter 6’s principles — separation of concerns, deterministic state management, security by design, targeted observability — are the kinds of constraints that should appear in ADR context when a team chooses how refunds, reversals, or store-and-forward sync are structured (the book, Ch. 6, 14).

Architecture is trade-off work

Richards and Ford argue that architecture is fundamentally about understanding and balancing trade-offs. There is rarely a universally correct choice. A log-oriented broker is not simply “better” than a work queue. Microservices are not simply “better” than a modular monolith. Event-driven flows are not simply “better” than synchronous request/response.

Each option improves some characteristics and degrades others. The productive question shifts from “What is the best technology?” to “Given our requirements and constraints, which trade-offs are we willing to accept?”

Spikes surface those trade-offs under load, latency, and failure. ADRs make the accepted set explicit. Software Architecture: The Hard Parts pushes the same style into decomposition, data ownership, coupling, orchestration versus choreography, and evolution — problems that rarely have perfect answers, only recorded compromises.

Payment systems sharpen the stakes: a wrong retry policy can double-post; a missing idempotency key can create chargebacks and reconciliation debt; a store-and-forward design that ignores scheme and liability constraints can pass a demo and fail certification (the book, Ch. 14–15).

Keep both practices light

Neither practice needs bureaucracy.

A Spike answers a question inside a time box. It should not become an open-ended research programme.
An ADR preserves a decision in a page or two. It should not become a 40-page design specification.

Question → Spike → Evidence → Trade-offs → Decision → ADR → Architecture

Months later, when someone asks why the system looks the way it does, the answer need not be tribal memory about an engineer who left. The reasoning is still in the repository, next to the code that implements it.

References

Nygard, M. — “Documenting Architecture Decisions,” Cognitect blog, 15 Nov 2011. https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions
Thoughtworks Technology Radar — Lightweight Architecture Decision Records (Adopt). https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records
Fowler, M. — “Architecture Decision Record” (bliki). https://martinfowler.com/bliki/ArchitectureDecisionRecord.html
Richards, M. & Ford, N. — Fundamentals of Software Architecture: An Engineering Approach (2nd ed.). O’Reilly.
Ford, N., Richards, M., Sadalage, P. & Dehghani, Z. — Software Architecture: The Hard Parts. O’Reilly.
Extreme Programming / Kent Beck — Spike Solution (time-boxed investigation before committing to an implementation).
Bevia, V. — Point-of-Sale Systems Architecture, Chapters 6, 14, and 15: https://corebaseit.com/my-books/
Corebaseit — Double charging; Offline EMV vs store-and-forward.