Architecture Decisions and Migration Paths

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production; see the section bibliography for the reference material consulted while preparing these pages.

Welcome to the Architecture Decisions and Migration Paths reference, one of the two halves of the Architecture reference. Where its sibling, Architectural Patterns, assumes a set of services already exists and shows how a split system stays consistent, this section comes first: it helps you decide whether and how to split a system in the first place — which architectural style fits, when a monolith is still the right call, how to separate backend and frontend, and, once a decision is made, how to actually get from where you are today to where you want to be, one safe step at a time. Every worked example in this section shares one running domain — Bookshop, a fictional online bookstore — shown first as a legacy Java EE/Struts monolith, then as a healthy Spring Boot monolith with five business capabilities (catalogue, orders, payments, shipping, customer accounts), and finally strangled, module by module and service by service, into a modular monolith, a set of microservices, and, in its own migration path, a multi-tenant SaaS product.

If you are new to this section, read Architectural Styles: Monolith, Modular Monolith, Microservices first, then Benefits and Drawbacks of Microservices, then Choosing: Monolith or Microservices?, then Layering: Isolating Backend and Frontend and API Gateway and Backends for Frontends, then Migration Overview: How to Approach Any Migration followed by the four migration paths — legacy stack, monolith to modular monolith, monolith to microservices, and single-tenant to multi-tenant SaaS — then Starting a New Project: Which Path and Which Technologies, and finally the Architecture Decisions and Migration Paths Cheat Sheet for a one-page summary of everything above.

What’s covered

Foundations

  • Architectural Styles: Monolith, Modular Monolith, Microservices — what a monolith, a modular monolith and a microservices architecture actually are, the scale cube as the vocabulary for scaling, and the distributed-monolith anti-pattern.

  • Benefits and Drawbacks of Microservices — what microservices give you — independent deployability, independent scalability, fault isolation — and what they cost, from distributed-system complexity to the loss of ACID transactions, illustrated with the Bookshop monolith’s growth into monolithic hell.

  • Choosing: Monolith or Microservices? — a plain-language decision guide for when a monolith (modular from day one) is the right choice, when microservices earn their keep, and the signals that it is time to split — or to merge back.

Layering the architecture

  • Layering: Isolating Backend and Frontend — moving from a monolith that renders its own HTML to a backend that exposes only an API behind a gateway, consumed by separate web frontends and native mobile apps, and when a server-rendered UI is still the simpler, better choice.

  • API Gateway and Backends for Frontends — why clients should not call services directly, what an API gateway does at the edge of a distributed system, the backends-for-frontends variant, and the off-the-shelf and build-your-own options for implementing one.

Migration paths

  • Migration Overview: How to Approach Any Migration — the balancing act, timing considerations, and universal principles — no big bang, the strangler fig, demonstrating value early — that apply to every migration path in this section, ending with a guide to which path fits your situation.

  • Migration Path: From a Legacy Stack to a Modern One — moving Bookshop off a legacy Java EE/Struts stack, mapping legacy technologies to their modern replacements, the strangler fig with a reverse proxy, separating presentation from backend first, branch by abstraction, the anti-corruption layer, data synchronisation, and the exit criteria for retiring the legacy system.

  • Migration Path: From a Monolith to a Modular Monolith — turning a healthy monolith into a modular monolith: identifying modules by business capability, enforcing boundaries with Spring Modulith and ArchUnit, replacing shared tables and object references with module APIs and events, killing god classes, and the signal that it is time to go further.

  • Migration Path: From a Monolith to Microservices — the centrepiece migration path: Richardson’s three service-extraction strategies, splitting the domain model, refactoring and replicating data, designing monolith-service collaboration, sagas that keep the monolith’s own transaction a pivot, security, and deployment, all worked through the Bookshop example step by step.

  • Migration Path: From Single-Tenant to Multi-Tenant SaaS — how Bookshop moves from single-tenant, installed software to a multi-tenant SaaS product: the control plane / application plane split, the silo/pool deployment models, three migration patterns, and the guiding principles that keep the move on track.

Starting from scratch

  • Starting a New Project: Which Path and Which Technologies — a practical starting point for a brand-new project: the profile questions to ask first, the default path (a modular monolith), seven scenario cards with a recommended stack drawn only from technologies documented on this site, and cross-cutting recommendation tables for framework, API style, messaging, database, frontend, mobile, auth, and deployment.

Reference

This section complements, rather than duplicates, Architectural Patterns: that section decides how a system that is already split into services keeps its data consistent — sagas, domain events, the transactional outbox, CQRS, event sourcing — while this one decides whether and how to split the system in the first place, and how to get there safely. Several other references document the mechanics this section only sketches. The SpringBoot Reference is where the Spring Modulith module boundaries, Spring Cloud Gateway routes, and Spring Boot conventions this section’s Bookshop examples build on are documented in full. The Quarkus Reference covers the Kubernetes-native alternative named throughout the new-project guide, including Narayana LRA as a saga-compensation mechanism. The Messaging Reference documents the Kafka and RabbitMQ mechanics — topics, Kafka Connect, change data capture — behind the domain-event publishing and data-synchronisation techniques the migration paths use. The GraphQL Reference is where a GraphQL-speaking gateway and the REST-vs-GraphQL trade-off, only sketched by the layering and gateway pages here, are covered in depth. The OAuth Reference documents the token-based authentication that replaces session cookies once a gateway or BFF sits in front of the backend. The Web Development reference documents every frontend framework this section’s layering and new-project pages recommend — React, Angular, Vue, Vaadin, Blazor, and more. And the Apps reference covers the native Android/Kotlin client used as this section’s mobile example.

Bibliography

The books above are consulted references only, never the primary source for any code example: on any discrepancy, the pattern authors' current online catalogues — microservices.io, the Fowler bliki, the cloud-provider architecture guides — and the framework documentation listed above are authoritative, and every code example in this section is verified against them at implementation time.