DEV Community: Saulo Santos

The AI Bridge Problem: Why Enterprise AI Integration Is an Architecture Challenge, Not an AI Challenge

Saulo Santos — Fri, 15 May 2026 15:52:08 +0000

The Wrong Conversation

Most of the enterprise AI conversation is happening at the wrong level.

Organisations are asking which model to use, which vendor to partner with, how to write better prompts, how to build a chatbot. These are reasonable questions. They are also largely the wrong ones for enterprises that have spent decades building complex, mission-critical systems.

The hard problem in enterprise AI adoption is not the AI. It is the bridge — between the intelligence that modern AI models offer and the systems, processes, and institutional knowledge that enterprises have built over twenty or thirty years. Building that bridge is fundamentally an architecture problem. And the engineers best positioned to solve it are not AI specialists. They are the architects who understand the legacy systems that AI needs to integrate with.

I have been working in enterprise software architecture for over twenty-five years, across financial services, insurance, and large-scale platform engineering. AI entered my working environment a few years ago as a supporting tool — a more intelligent search, useful for generating scripts and solving isolated problems faster. What has happened since then is not an incremental improvement. It is a structural shift in how software gets built and how enterprise systems need to evolve to participate in it.

This article is about that shift — what it actually looks like in practice, why most enterprises are approaching it incorrectly, and what the architectural thinking behind real AI integration looks like.

What Changed and What Didn't

The first thing AI changed in my day-to-day work was the cost of implementation. Tasks that previously required days of careful coding — scaffolding a service, generating boilerplate, writing test coverage, producing documentation — collapsed to hours. More significantly, a framework that would realistically have taken three to four months to design and build to a production-ready standard was completed in two to three weeks, with the same level of architectural rigour and safety that the longer timeline would have produced.

This is the part of the AI productivity story that gets reported accurately. What gets reported less accurately is what made that acceleration possible.

It was not that AI replaced engineering judgment. It was that AI eliminated the bottleneck between architectural thinking and working code. The quality of the output was directly proportional to the depth of the requirements, the precision of the constraints, and the architectural decisions made before a single line was generated. Junior engineers using the same tools produced different results — not because the model treated them differently, but because directing an AI agent at the level of abstraction required for production-grade enterprise software requires the kind of domain knowledge and architectural judgment that comes from years of working on systems that cannot fail.

Seniority became more valuable, not less. The conversation with an AI agent in a complex enterprise context is itself a high-skill activity. It requires knowing what questions to ask, what constraints to specify, what failure modes to anticipate, and when to override a generated decision that is technically correct but architecturally wrong for the context. That capability is not democratised by AI — it is amplified by it.

The Organisational Transformation

Individual productivity is the visible part of the shift. The less visible part is what happens to organisations when that productivity becomes the baseline expectation.

The challenge is not getting individual engineers to use AI tools. Most will, quickly, because the productivity benefit is immediate and obvious. The challenge is redesigning how engineering organisations work when the cost of implementation has fundamentally changed.

In practice this means several things. Repetitive and mechanical tasks — the kind that previously consumed significant engineering capacity — become candidates for AI-assisted acceleration or elimination. The work that cannot be accelerated in the same way — architectural decisions, system design, cross-domain trade-off analysis, understanding the behaviour of complex legacy systems under edge conditions — becomes a larger proportion of what senior engineers actually do.

It also creates a new kind of pressure. If implementation is faster, the expectation for delivery accelerates. If one engineer can produce what previously required a team, the question of what the team should be doing with its freed capacity becomes urgent. Organisations that answer that question well — by redirecting capacity toward higher-order architectural work, system modernisation, and AI integration itself — will compound their advantage. Those that simply reduce headcount will discover that the institutional knowledge they eliminated is exactly what they needed to direct the AI work effectively.

The companies that win the AI transition are not the ones that adopt AI fastest. They are the ones that redesign their engineering organisations around what AI makes possible while preserving the expertise that makes AI useful.

The Continuity Risk Nobody Is Talking About

There is a dimension of the AI transition that is not getting enough attention, and it concerns me more than any of the technical challenges.

Implementation is how junior engineers learn.

The struggle of writing code from scratch — the debugging, the failed attempts, the gradual understanding of why a system behaves the way it does under specific conditions — is not inefficiency. It is the formation process for expertise. When a junior engineer spends three days tracking down a concurrency issue in a distributed system, they are not wasting time. They are building the mental model that will, a decade later, allow them to immediately recognise the same pattern in a different system and know exactly where to look.

AI makes implementation cheap. That is the gain everyone is celebrating. But if implementation becomes something you describe to an agent rather than something you do yourself, the formation process changes fundamentally. The question the industry is not asking loudly enough is: where do the next generation of senior architects come from?

The senior engineers directing AI agents effectively today are doing so because they have ten, fifteen, twenty years of hard-won understanding about how complex systems actually behave — not how they are supposed to behave, but how they behave under load, under failure, under the pressure of a production incident at two in the morning. That understanding was not learned from documentation. It was learned by being in the system, making mistakes, and absorbing the consequences.

If junior engineers spend their formative years describing requirements to AI agents and reviewing generated output, they will develop a different kind of expertise — and it is not clear yet whether that expertise will be sufficient to lead the next generation of AI-directed engineering, or whether it will produce a generation of engineers who are highly productive with AI assistance but brittle without it.

The organisational incentive structure makes this worse. Companies optimising for immediate delivery will measure junior engineers by output rather than growth. Graduate programmes will be reduced or repositioned. Mentoring investment will be deprioritised in favour of tooling investment. These are rational short-term decisions. They are potentially catastrophic long-term ones.

The knowledge that makes AI genuinely useful in a specific enterprise context — the deep familiarity with how a specific system behaves, what the edge cases are, where the undocumented assumptions live — is not produced by AI. It is produced by humans who spent years working closely with those systems. When the current generation of senior architects moves on, the organisations that did not invest in developing their successors will discover they have built AI-augmented mega-infrastructures that nobody has the depth to maintain, evolve, or redirect when the AI produces something wrong.

This is not an argument against AI adoption. It is an argument for thinking carefully about what the engineering career path looks like in an AI-enabled world, and ensuring that the path still produces the depth of expertise the industry will need. The companies that figure this out — that find ways to accelerate junior engineers with AI while still ensuring they develop genuine systems understanding — will have a significant long-term advantage over those that simply optimise for immediate output.

The hard skills are not obsolete. They are becoming rarer. And rarer, in the long run, means more valuable — provided we do not stop producing them entirely.

The Bridge Problem in Enterprise Architecture

Individual productivity and organisational transformation are both real. But neither of them addresses the core architectural challenge that most enterprise organisations have not yet confronted directly.

Enterprise systems carry decades of business logic. Insurance platforms, banking systems, ERP installations — these are not just software. They are encoded institutional knowledge. Pricing rules accumulated over fifteen years. Claims processing logic refined through thousands of edge cases. Integration patterns built around the specific quirks of third-party systems that have since been acquired, renamed, and partially deprecated. This knowledge does not exist cleanly in documentation. It exists in running code.

AI models — even the most capable ones — do not have access to this knowledge by default. A general-purpose model can answer general questions. It cannot reason about the specific behaviour of a proprietary claims processing engine, apply the pricing rules encoded in a twenty-year-old policy management system, or navigate the undocumented integration contracts between internal systems that have accumulated over decades.

The gap between what AI can do in isolation and what it needs to do to be genuinely useful in an enterprise context is not a model capability problem. It is a knowledge integration problem. And solving it requires architectural thinking.

What Real AI Integration Looks Like

The architectural pattern that addresses this is not connecting a chatbot to an API. It is the deliberate design of a bridge layer between enterprise systems and AI agents — a layer that understands both the AI's capabilities and the enterprise's constraints, and translates between them.

In practice this means several components working together.

A dedicated AI integration service sits between the enterprise application ecosystem and the AI agents. It does not expose the full complexity of the underlying systems to the AI. Instead, it presents a controlled, well-defined interface — specific capabilities, specific data, specific operations — that the AI agent can reason about reliably. This is the same principle as an Anti-Corruption Layer in domain-driven design: the new system should speak its own language, not be polluted by the legacy system's constraints.

Domain-specific AI agents are trained or configured with the institutional knowledge that makes them useful in the specific enterprise context. This is where the twenty-plus years of industry experience becomes the real asset. General models answer general questions. Models grounded in specific domain knowledge — the pricing logic of a particular insurance product, the compliance rules of a specific regulatory environment, the operational patterns of a specific industry vertical — answer the questions that actually matter. The intelligence is not just in the model. It is in the knowledge used to specialise it.

Integration with both legacy systems and the new microservice layer ensures the AI agent can act on what it knows. Read access to legacy data, write access through controlled APIs, event-driven integration with the modern service layer — the bridge needs to connect in both directions. An AI agent that can reason correctly but cannot act on its reasoning has limited value. The architectural work is making action possible without compromising the integrity of the systems being acted on.

This pattern is not theoretical. The architectural problems it addresses — how to give AI agents access to domain-specific knowledge without exposing the full complexity of underlying systems, how to integrate with both legacy components and modern services without duplicating that integration across every application that needs it, how to make AI capabilities available consistently across an enterprise ecosystem — are the same problems that any serious AI integration effort in a complex enterprise environment will encounter. The difference between organisations that solve them well and those that don't is whether they approach AI integration as an architecture problem from the start.

Building AI-Native From the Start

The bridge problem looks different when you are not constrained by existing systems. Recently I have been involved in a greenfield project that applies the same architectural principles from a clean starting point — the opportunity to design the system around AI capabilities from the foundation rather than integrating AI into something already built.

The goal of the platform is to encode decades of specialist domain expertise into an AI-native system — to take the judgment, patterns, and accumulated knowledge that experienced practitioners in a specific field have developed over twenty-plus years, and make that intelligence available at scale through software. The AI is not a feature of this system. It is the core of it.

What makes this architecturally interesting is how the system handles knowledge accumulation over time. Rather than relying solely on a general model's training, the system builds and maintains a curated library of approved outputs — domain-specific examples, patterns, and approaches — each embedded as a vector representation and retrieved by similarity to the current request at inference time. The model receives not just a prompt but a set of contextual anchors drawn from the library that encode the accumulated expert judgment of the domain. The output improves over time not because the model changes but because the knowledge available to it improves.

The system is designed around an event-driven pipeline where generation steps run concurrently rather than sequentially — multiple workstreams happening in parallel, orchestrated through a message bus, with a state machine managing the lifecycle from initial signal extraction through to final assembly. Each step is independently deployable and independently scalable. The knowledge library sits alongside this pipeline, consulted at each generation step rather than once at the start, so that the domain expertise influences not just the initial prompt but every stage of the output.

This is the same principle as the enterprise AI bridge, applied in a greenfield context. In both cases the core architectural insight is identical: a general model given general inputs produces general outputs. The same model given structured domain knowledge — curated, maintained, and retrieved intelligently — produces outputs that reflect genuine expertise.

Both contexts point to the same conclusion. The value of AI in a software system is not a function of which model you use. It is a function of the quality of the knowledge and context you bring to the model.

What Most Organisations Get Wrong

The most common mistake in enterprise AI adoption is treating it as a layer rather than a system.

Adding AI as a layer means connecting a general-purpose model to existing systems through an API and expecting it to become useful. This produces chatbots that can answer questions about publicly available information but cannot reason about company-specific data. It produces automation that works on simple, well-defined tasks but fails on the edge cases that are precisely where human judgment was most needed. It produces AI features that are impressive in demos and disappointing in production.

The reason is that a layer does not have access to the knowledge that makes AI useful in a specific context. It has access to the model's general training. General training is sufficient for general tasks. Enterprise problems are not general.

Treating AI as a system means designing the knowledge integration deliberately. It means deciding which domain knowledge needs to be made available to AI agents and in what form. It means building the bridge layer that translates between AI capabilities and enterprise constraints. It means curating, structuring, and maintaining the institutional knowledge that makes AI useful rather than assuming the model will figure it out from raw system access.

This is architectural work. It requires the same judgment, the same understanding of trade-offs, the same discipline around boundaries and contracts that any serious systems architecture requires. It is not prompt engineering. It is not model selection. It is system design.

The Race That Is Already Running

There is a competitive dimension to this that cannot be ignored.

Organisations that build the AI bridge effectively will compound their advantage over time. The knowledge library grows. The integration layer matures. The AI agents become more capable in the specific domain context. The gap between what they can do with AI and what a competitor starting from scratch can do widens with every month.

Organisations that do not build the bridge — that add AI as a layer, or wait for the technology to mature further, or focus on internal productivity without addressing the integration problem — will find themselves in an increasingly difficult position. Not because they lack AI access. Because their competitors will have AI that understands their domain, and they will not.

The race is not about who adopts AI first. It is about who builds the knowledge infrastructure that makes AI genuinely intelligent in their specific context. That infrastructure is architectural. It takes time to build. And the organisations that understand this are already building it.

Conclusion

Enterprise AI integration is not a technology selection problem. It is an architecture problem, and it is one of the most consequential architecture problems the industry has faced in a generation.

The engineers who will solve it are not the ones who know the most about AI models. They are the ones who understand the systems that AI needs to integrate with — the legacy platforms, the institutional knowledge, the operational constraints, the integration patterns that have accumulated over decades of real-world use.

That depth of understanding is not produced quickly. It is not replicated by a certification or a prompt engineering course. It is built through years of working on systems that cannot fail, in environments where the consequences of getting it wrong are real.

The bridge needs to be built. The question is whether the people building it understand both sides — and whether the industry is investing in producing the next generation of people who will.

This article is Part 4 of the Incremental Modernization Architecture series.
Part 1: Enabling Observability in Legacy Systems
Part 2: Splitting Monoliths into Microservices Without Breaking the Business
Part 3: Designing Multi-Tenant Extensibility for Enterprise SaaS

Incremental Modernization Architecture: Designing Multi-Tenant Extensibility for Enterprise SaaS

Saulo Santos — Thu, 14 May 2026 19:45:23 +0000

The Problem the Industry Hasn't Solved Yet

Most enterprise software vendors are solving a SaaS customisation problem with tools designed for on-premise delivery. The inheritance model — customers extending platform behaviour through Java class hierarchies, compiled and packaged alongside core — was the right answer for its era. Every customer ran their own installation. Upgrade timelines were theirs to own. The coupling between core and customisation was manageable because the delivery model absorbed it.

That era is over. SaaS delivery, continuous releases, and multi-tenant operations have changed the requirements completely. But the architecture most vendors are working with has not kept pace. The result is visible and quantifiable: upgrade projects that consume six to nine months of a medium-sized team's capacity, SaaS roadmaps constrained by the need to maintain backward compatibility across thousands of customer customisations, and customers who stay on old releases not because they want to but because upgrading costs too much.

This is not a problem any single vendor created. It is a structural property of successful, deeply adopted enterprise software — the kind that SAP, Oracle, Guidewire, and others have all built. I have been working on exactly this class of platform: a large-scale enterprise system managing complex business entities, workflows, and integrations across multiple lines of business, built over two decades and customised deeply by every customer who uses it.

The question is not whether the old model served its purpose — it did. The question is what replaces it, and why most attempts at replacement fall short.

Why the Obvious Solutions Don't Work

The first instinct is usually configuration. If customers can configure behaviour rather than extend it in code, the coupling disappears. This works up to a point — typically the point where a customer's requirement is genuinely novel and cannot be expressed through the options the platform anticipated. Configuration systems solve the common cases. They fail exactly when customers need them most.

The second instinct is a plugin system. Expose stable APIs, let customers implement them, load the implementations at runtime. Better — but a plugin system without enforced boundaries gradually accumulates plugins that reach into platform internals the API was never meant to expose. The coupling re-emerges, just less visibly. And in a multi-tenant environment where plugins from different customers run in the same process, one misbehaving plugin can affect every other customer on the instance.

The third instinct — the one most teams eventually reach — is microservices. Move customisation out of the monolith entirely. Make it someone else's deployment problem. This works for some use cases and fails for others. An extension that needs to participate in the platform's database transaction cannot run in a separate process. An extension that needs sub-millisecond latency cannot absorb a network round-trip. Microservices push the problem rather than solving it.

What is actually needed is a framework that satisfies constraints that pull in different directions simultaneously: extensions that can run in-process or out-of-process depending on their requirements, with a consistent programming model across both; tenant isolation that is enforced structurally, not by convention; hot deployment without downtime; and trust boundaries that the platform controls, not the extension author. Getting all of these right at the same time, on top of a live platform that cannot be taken offline, is where the hard work lives.

The First Decision: Explicit Over Implicit

The most consequential early decision is whether extension points are explicit or implicit.

Implicit extensibility — anything can be overridden, any class can be subclassed, any behaviour can be intercepted — looks maximally flexible. In practice it produces systems where the platform team has no stable contract to maintain, extension authors reach into internals never designed to be touched, and refactoring becomes dangerous because any rename or restructure might silently break an extension somewhere in a customer's codebase. The coupling is invisible until it breaks, and it always breaks at the worst time.

Explicit extensibility inverts this. Core developers deliberately mark which methods are extension points and define what each phase of execution can do. This feels more restrictive — and it is, intentionally. The restriction is the value. The platform owns a stable, versioned contract. Extension authors work against a documented surface. Both sides evolve independently within their boundaries.

The discipline of deciding which methods to expose also forces useful thinking. It surfaces questions that should be asked anyway: what is the intended behaviour of this method, what state is safe to share with an extension at this point, what happens if an extension here throws. Answering those questions at design time is far cheaper than discovering the answers in a production incident at a customer site.

The Interception Model

Once explicit extension points are the decision, the interception mechanism is the next critical choice — and this is where most teams make a mistake they later regret.

Proxy-based interception is the default. It is easy to implement, well understood, and supported by every major Java framework. It is also fundamentally limited in a way that matters enormously in enterprise codebases: a proxy wraps an object, not a class. Calls made from within the same class — this.method() — bypass the proxy entirely. In a system built over twenty years with deep internal call chains, this is not a theoretical edge case. It is a daily occurrence. Extensions register correctly, the logs show them loading, and they simply never fire.

Compile-time bytecode weaving rewrites the compiled class files directly. The interception point is in the bytecode itself — it fires regardless of how the method is called, externally, internally, through a superclass, through a delegation chain. The build pipeline is more complex. The behaviour is reliable. On a codebase that was not designed from the ground up with extensibility in mind, reliable beats elegant.

The execution model that follows is a three-phase system: logic that runs before the core operation, logic that replaces it entirely, and logic that runs after it completes.

The phase model also makes failure handling tractable. A PRE hook that throws can abort the operation cleanly before anything is written. A POST hook that throws can be handled independently of the core outcome. An OVERRIDE hook that throws owns the failure semantics entirely. Each case has defined, predictable behaviour — which means both extension authors and platform operators can reason about failure modes before they encounter them in production.

The Trust Problem

The hardest design question in extensibility is not technical. It is about trust.

The naive position is to trust extension authors to behave responsibly. This is reasonable for internal teams building extensions on a platform they also operate. It is not reasonable for a SaaS platform where extensions come from dozens of independent vendors and customers, built by teams with varying levels of experience, deployed into a shared environment where a failure in one extension can affect every other tenant on the same instance.

The alternative is to make the platform's boundaries enforced rather than conventional. The platform decides — not the extension author — what extension code can access, what it can modify, and what operations it can perform. If an extension attempts to reach outside its permitted scope, the platform stops it. Not with a code review comment. Structurally.

Two consequences follow from this.

First, enforcement needs to happen at multiple levels. Checking only at deployment means a buggy extension causes damage before the check runs. Checking only at runtime means the feedback loop for extension authors is slow and the discovery happens in a customer environment. The right model layers the checks: some during the extension's own build process, some when the extension registers with the platform, some at runtime as a final line. Each layer catches different failure modes. None of them alone is sufficient.

Second, state protection has to be explicit. When an extension runs in the same process as the core platform, it shares the heap. An extension that receives a domain object has a direct Java reference to that object. Without enforcement, it can modify that object — and the modification will be visible to whatever core logic reads it next. The mechanism for preventing this needs to be applied consistently at every point where objects cross the boundary from platform into extension code. Convention does not hold across hundreds of extensions from dozens of vendors over years of operation.

Multi-Tenancy: One Instance, Many Customers

This is where the extensibility framework intersects most directly with the SaaS business model — and where getting it wrong has the most visible consequences.

The goal is a single running application instance serving multiple customers simultaneously, each with their own active extensions, with complete isolation between them. A hook registered for customer A never fires for customer B. An extension update for one customer does not interrupt another customer's in-flight session. A new customer can be onboarded — extensions loaded, registered, made active — without restarting anything.

The architectural key is that tenant identity has to flow through the entire call chain automatically. Every incoming request carries a tenant identifier. Every hook lookup is scoped to it. The registry merges two sets at dispatch time: extensions that apply globally across all tenants, and extensions specific to the current customer. The merge is invisible to both the core application and the extension authors.

The layer model adds nuance that flat extensibility cannot represent. Enterprise platforms operate with multiple tiers — corporate standards that apply universally, regional rules that apply to specific markets, individual customer configurations that are the most specific of all. A flat model collapses these tiers and forces every customer to re-implement logic they never intended to own. A configurable hierarchy preserves the tiers, with deterministic resolution when layers conflict.

Hot-reload is non-negotiable in a SaaS context — and it is harder than it looks. Simply swapping the old extension for the new one risks interrupting executions that are partway through a hook invocation. The right approach tracks in-flight executions, waits for them to complete, then unloads the old code and loads the new code into the now-empty context. Other tenants are entirely unaffected. The operational benefit — zero-downtime deployment for every extension update — justifies the implementation complexity.

Two Runtimes, One Contract

One of the harder design goals is supporting both in-process and out-of-process execution with a single programming model. The temptation is to pick one and optimise for it. Both are wrong choices.

In-process execution is not optional for extensions that participate in the platform's database transaction. If an extension modifies data that the core operation is about to write, that modification must be part of the same commit or the same rollback. A network round-trip cannot be part of a transaction boundary. For these cases, in-process is the only correct answer.

Out-of-process execution is the right model for extensions that react to completed operations rather than participate in them. Notifications, downstream workflow triggers, audit writes — none of these need transactional coupling with core. Running them out-of-process gives them independent deployment, independent scaling, and complete isolation from the core platform's failure modes. Forcing them in-process is unnecessary risk.

The design decision that resolves this is to define the contract at the level of the extension author's experience, not at the level of the execution mechanism. Extension authors write to a single context API and declare their execution preference in metadata. The framework handles in-process invocation or network serialisation transparently. An extension author should not need to understand the difference between the two to write correct extension code.

Deferred post-commit execution eliminates an entire class of distributed consistency problems. An extension that declares it should fire after the transaction commits will never fire on a rollback — the platform guarantees this. If the extension itself fails after a successful commit, the failure is handled independently. The extension author states the intent. The platform owns the guarantee.

What Changes

The contrast with the inheritance model is not subtle.

For the platform team, a core release no longer requires coordinating with every customer's development team to analyse the impact on their customisations. The published extension point catalog is the contract. If a customer's extension compiles against it, the upgrade is compatible. If it doesn't, the incompatibility is visible immediately — not six months later during a migration project.

For customers, a business rule change that previously required a platform upgrade cycle can be deployed as an extension update — tested, validated, and live without touching the core system. New tenants onboard into a running instance without downtime for anyone else.

For the engineering organisation, the six-to-nine-month upgrade project becomes a compatibility check and a deployment step. The performance campaign that had to model the emergent complexity of deep inheritance hierarchies becomes per-extension metrics — latency, error rate, timeout rate — per tenant, in standard observability tooling.

The underlying shift is from coupling to contract. Inheritance couples extension code to core code permanently. A hook-based framework with explicit extension points, enforced boundaries, and versioned contracts decouples them — while keeping the flexibility that made the old model worth building in the first place.

The Tension That Remains

Designing this kind of framework surfaces a tension that does not fully resolve — it only gets managed.

Extension authors want maximum flexibility. Every constraint the framework imposes is, from their perspective, a limitation. Platform operators want maximum control. The tighter the boundaries, the more predictable the system's behaviour under load, under failure, and under a misbehaving extension.

Both positions are legitimate. The framework designer's job is not to pick a side but to find the boundary where the platform's constraints are structural — not guidelines that extension authors are expected to follow — while leaving genuine flexibility within that boundary.

Getting this wrong in either direction is costly. Too permissive, and the framework gradually accumulates extensions that reach into platform internals, recreating the coupling it was designed to eliminate. Too restrictive, and customers work around it through mechanisms the framework cannot see or control, which is worse than having the flexibility in the first place.

The goal is a framework where trust is architecturally guaranteed within a well-defined boundary. Not assumed. Not enforced by convention. Guaranteed by design.

Most enterprise platforms are still further from that goal than they publicly acknowledge. The inheritance model is being refined rather than replaced, and the cost continues to compound. The industry has the patterns it needs — explicit extension points, enforced boundaries, independently deployed tenant logic have all existed in various forms for decades. What is new is the scale and complexity of the platforms that need them, and the urgency of the SaaS transition that makes the status quo increasingly untenable.

That is the problem worth solving. And it is further from solved than most roadmaps suggest.

This article is Part 3 of the Incremental Modernization Architecture series.
Part 1: Enabling Observability in Legacy Systems
Part 2: Splitting Monoliths into Microservices Without Breaking the Business

Incremental Modernization Architecture: Splitting Monoliths into Microservices Without Breaking the Business

Saulo Santos — Sat, 02 May 2026 17:10:12 +0000

A Pragmatic Approach to Service Decomposition

For many enterprises, the monolith is both a strength and a challenge. Over decades, organizations build robust platforms that support critical operations — but eventually, the weight of legacy coupling begins to hinder growth.

Successful modernization is less about "new tech" and more about managing the transition of complexity.

The real question is never "should we modernize?" — it is "how do we modernize without stopping the business that funds the modernization?"

A Tale of Two Modernizations: Lessons from the Field

I have lived through two very different modernization efforts — separated by roughly two decades, different companies, different scales, different outcomes. What they share is that the architecture of the transition mattered far more than the architecture of the target system.

Case 1: The Language Migration Trap (The "Big Bang" Failure)

Early in my career, I was part of a company that decided to rewrite its entire monolith into Java J2EE. This wasn't an incremental evolution — it was a full stop, full swap. Legacy maintenance was put on pause. The "New World" was everything.

Looking back now, the failure modes are clear.

The first was customer patience running out. While the team was absorbed in the rewrite, real business demands kept coming. Support tickets piled up. Feature requests went unanswered. The old system was frozen, and the new one wasn't ready. There is only so long a customer base will tolerate that gap before the relationship breaks.

The second was over-ambition in the architecture itself. The lead architect — talented, no question — went deep into building a universal framework that would auto-generate screens and business logic. The idea was impressive on paper. In practice, the generated code was slow and inflexible, and the framework became a bottleneck. Every change required fighting the abstraction rather than solving the business problem. Code reviews turned into painful rework cycles. Development slowed to a crawl.

Here is the hard lesson: they built it because they could, not because the business needed it. There was no real requirement driving the need to regenerate screens automatically. It was engineering ambition outrunning business reality.

The frustration compounded over time. Engineers lost momentum. Team morale eroded. About two years after I left, the company went bankrupt.

Not because of bad engineers. Because of an approach that put architectural purity ahead of continuous value delivery.

Case 2: The Microservices Evolution (The Balanced Win)

Years later, leading the web and API team at a UK insurance technology firm, I faced a different challenge. We had a large integration monolith — not a traditional business logic monolith, but a complex orchestration layer connecting our core insurance processing platform (handling policies, contacts, claims and more) with banking validation, payment processing, and a range of custom-built internal services. It was the nervous system of the operation.

The goal was to decompose this into microservices. The constraint was that we could never stop the business while doing it.

We allocated 15–20% of development capacity to the migration. The rest kept the platform running and delivering features. We applied the Strangler Fig pattern — gradually routing traffic away from the monolith and toward new, purpose-built services, while both coexisted in production for an extended period. There was no hard cutover. There were instead many intermediate states, each stable enough to operate in, each a step closer to the target architecture.

It worked. Not because we were faster or smarter than the team in Case 1 — but because we never stopped serving the business while we transformed it.

Engineers had room to learn new technologies — microservices patterns, event-driven architecture, modern API design — without being pulled entirely away from the systems that mattered today. That balance kept frustration low and momentum high.

The Strangler Fig in Practice

The Strangler Fig pattern deserves more than a passing mention, because it is the architectural mechanism that makes incremental decomposition possible.

The principle is straightforward: rather than replacing a system in one move, you grow new capability around it. New requests are routed to the new service. The monolith handles what hasn't been migrated yet. Over time, the monolith "strangles" — its surface area shrinks as each capability is extracted — until it can eventually be retired, or simply left running the small residual it still owns.

In our case, the monolith was an integration and transformation layer. Extracting from it meant two distinct types of work:

Service extraction — identifying discrete integration flows (say, payment processing or banking validation) and pulling them out as standalone services with their own deployment lifecycle.
Transformation layer rewriting — where the monolith was doing complex schema and API transformations between systems, we rewrote those translation responsibilities into a new architecture, giving us cleaner contracts and independent evolvability. Neither of these was a clean, surgical operation. Real systems aren't clean. The intermediate states — where both the old and new paths existed simultaneously — required careful routing logic, thorough testing at the boundary, and a tolerance for living with complexity during the transition. That tolerance is itself an architectural decision. You have to accept that the system will look messy for a while. The alternative is a Big Bang that looks clean on a diagram and fails in production.

The Strangler Fig trades short-term tidiness for long-term survivability. That is almost always the right trade.

The Boundary Problem: Strategic vs. Tactical

Both stories surface the same underlying challenge: where do you draw the line?

In software, we tend to think of this as a technical question — bounded contexts, API contracts, data ownership. But in practice, it operates at three levels simultaneously:

Logical Boundaries (Domain-Driven Design): Ensuring that a change to payment processing doesn't cascade into claims, and that each service owns its own model cleanly.
Implementation Boundaries (Anti-Corruption): When integrating with a third-party platform that has its own data model and terminology, you need a translation layer that protects your new services from absorbing legacy concepts. Your domain language should stay yours.
Operational Boundaries (Capacity): This is the one most teams ignore. How much architectural change can your organisation absorb per sprint without compromising delivery? That is a real constraint, and it needs to be treated as one. Most failed modernizations violate all three simultaneously — trying to redesign the domain model, integrate legacy systems, and restructure the team all at once.

The Human Side of Transformation

This is the part that rarely makes it into architecture documents, but it determines outcomes as much as any technical decision.

In Case 1, the human cost was visible in hindsight. Engineers were asked to build an entirely new world while the old one decayed around them. The framework they were building didn't give them small wins — it was all or nothing. When the abstraction fought back, there was no relief valve. Frustration accumulated quietly until the team began to leave.

In Case 2, the 15–20% model created a different dynamic. Engineers were working on modern technology and shipping production value in the same sprint. Learning didn't come at the cost of delivery. People could see the migration moving forward in concrete steps — a service extracted, a transformation layer replaced — without feeling like the business was being held hostage to the architecture.

There is also a knowledge dimension that is easy to underestimate. A monolith built over many years carries encoded business logic that exists nowhere else — not in documentation, not in the heads of current team members, but in the behaviour of the running system. A Big Bang rewrite forces you to rediscover all of that logic under pressure, at the worst possible time. An incremental approach surfaces it gradually, giving the team time to understand it and encode it correctly in the new services.

The domain knowledge in legacy code is an asset. Treat it as such.

The 15–20% Capacity Model: Governance, Not Just a Number

The capacity allocation deserves its own framing, because it is often misread as a conservative compromise. It isn't. It is a governance model that answers a question most modernization programs never ask explicitly:

At what rate can this organisation absorb architectural change without compromising delivery?

The constraint is intentional. By capping the modernization investment, you force prioritization. Only the highest-value boundaries get addressed first. Engineers can't disappear into abstraction for quarters at a time. Stakeholders see continuous delivery alongside the transformation, which preserves the trust that long modernization programs tend to erode.

And it compounds. Early investments in shared infrastructure — service templates, deployment pipelines, observability tooling — reduce the cost of each subsequent extraction. The 20% buys you more over time, not less.

Modernization becomes a capability, not a project.

Strategic Principles for Success

Avoid technology for technology's sake. If a framework doesn't solve a current business requirement, it is a liability, not an asset. Case 1 is the cautionary example.
Modernize the path, not just the destination. The process of decomposing a monolith is as important as the target architecture. Design the transition, not just the end state.
Apply the Strangler Fig deliberately. Accept intermediate states. Plan for them. Route carefully, test the boundaries, and retire the old paths only when the new ones are proven.
Protect your domain model. When integrating with legacy systems or third-party platforms, use translation boundaries to keep your new services speaking your language, not theirs.
Budget for evolution. A fixed capacity allocation turns transformation from a high-stakes project into a continuous architectural practice.
Use observability as a compass. Instrument the system before you decompose it. Traces will show you where the real boundaries are — and validate that your extractions are actually working. (See Part 1 of this series for how to introduce observability non-invasively.)

Conclusion

Whether you are migrating into a new technology or decomposing an integration monolith into microservices, the path to success is the same: pragmatic incrementalism.

Modernization is not a single event. It is a strategic design choice to build the future without abandoning the present.

The strongest architectures are not those that are the most "pure" — they are those that are the most resilient to change. And resilience, in architecture as in engineering, is built through deliberate, sustained, small steps — not through a single leap of faith.

The monolith served the business for a reason. Your job is not to condemn it.

Your job is to evolve it — without breaking it.

This article is Part 2 of the Incremental Modernization Architecture series.

Part 1: Enabling Observability in Legacy Systems

Incremental Modernization Architecture: Enabling Observability in Legacy Systems

Saulo Santos — Sat, 02 May 2026 16:11:37 +0000

A Pragmatic Approach to Enterprise Modernization

Many corporations have spent more than a decade building what were once considered “perfect” monoliths — robust, feature-rich systems that power critical business operations. Today, however, these same systems are often viewed as obstacles: difficult to scale, hard to maintain, and incompatible with modern cloud-native architectures.

This creates a fundamental question for enterprise leaders: Should we throw everything away and start from scratch?

In practice, organizations that attempt a full rewrite — pausing legacy maintenance in favor of a “big bang” transformation — frequently fail. Costs spiral, delivery timelines slip, and business continuity is jeopardized. On the other hand, companies that adopt a step-by-step modernization strategy are far more likely to succeed.

This article focuses on one critical piece of that journey:
observability enablement in legacy systems — without requiring extensive code changes.

The Observability Gap in Legacy Systems

Modern distributed systems rely heavily on observability — metrics, logs, and traces — to provide insight into runtime behavior. In microservices architectures, observability is often built in from the start.

Legacy systems, however, present a different reality:

Limited or inconsistent logging
No distributed tracing capabilities
Tight coupling between components
High resistance to invasive code changes

Yet, observability is not optional. It is essential for:

Diagnosing production issues
Understanding system performance
Supporting gradual modernization
Enabling reliable integration with new services

The challenge becomes clear:
How do you introduce observability into systems that were never designed for it — without rewriting them?

Rethinking Modernization: Enable, Don’t Replace

A common misconception in modernization programs is that legacy systems must be replaced before they can participate in modern architectures.

In reality, modernization is not a replacement exercise — it is an enablement strategy.

Instead of rebuilding everything, organizations should:

Extend legacy systems with modern capabilities
Introduce abstraction layers and integration points
Gradually evolve architecture through coexistence

Observability is one of the most impactful capabilities to introduce early, because it:

Reduces operational risk
Accelerates debugging and issue resolution
Provides visibility into system behavior during transformation

Non-Invasive Observability: A Practical Approach

To enable observability without rewriting legacy systems, organizations can adopt non-invasive instrumentation techniques. These approaches allow telemetry to be introduced externally or at runtime, avoiding large-scale code changes.

1. Bytecode Instrumentation

Bytecode instrumentation enables runtime modification of application behavior without altering source code. By injecting telemetry logic dynamically, organizations can:

Capture method-level execution traces
Measure performance across critical flows
Introduce distributed tracing across legacy components

This approach is particularly effective in large Java-based systems, where rewriting code is impractical.

2. Agent-Based Observability

Instrumentation agents (such as those aligned with OpenTelemetry standards) can be attached to running applications to automatically collect:

Metrics (CPU, memory, throughput)
Logs (structured and correlated)
Traces (request-level visibility)

These agents operate independently of application code, making them ideal for legacy environments where direct modification is risky or costly.

3. Build-Time Tooling and Plugins

Another approach is to introduce observability during the build process using tools such as:

Maven or Gradle plugins
Annotation processors
Bytecode enhancement frameworks

These mechanisms allow developers to:

Inject telemetry hooks automatically
Enforce consistent observability patterns
Reduce manual implementation effort

Over time, this creates a standardized observability layer across both legacy and modern components.

4. Proxy and Gateway Instrumentation

In integration-heavy systems, observability can also be introduced at the boundaries:

API gateways
Reverse proxies
Service mesh layers

This enables:

Request tracing across systems
Latency measurement between services
Visibility into external dependencies

While this does not replace internal instrumentation, it provides immediate value with minimal disruption.

Real-World Implementation: Enabling Observability in a Large-Scale Legacy Platform

To apply these principles in practice, we implemented a non-invasive observability layer across a large-scale enterprise platform composed of multiple legacy Java applications and evolving microservices.

Rather than introducing manual instrumentation across thousands of methods — which would have been slow, error-prone, and difficult to maintain — we built a custom Maven-based bytecode enhancement plugin.

A Build-Time Instrumentation Strategy

At the core of the solution was a Maven plugin responsible for post-compilation bytecode transformation.

This was not a simple annotation injector, but a rule-driven bytecode enrichment engine designed to selectively introduce observability based on configurable policies rather than blanket instrumentation.

Instead of modifying source code, the plugin:

Intercepts compiled .class files during the build lifecycle
Injects observability-related annotations directly into bytecode
Preserves original line numbers to ensure debugger compatibility
Avoids any changes to developer-written source code

This allowed us to introduce observability without impacting day-to-day development workflows.

Selective and Rule-Based Instrumentation

A key design decision was avoiding blanket instrumentation.

Not every method should be traced.

To prevent unnecessary performance overhead, we introduced a rule engine based on regex matching, allowing instrumentation to be selectively applied at multiple levels:

Package level (e.g. com.company.billing.*)
Class level
Method level
Parameter level

This was fully parametrised as plugin configuration and ensured observability was applied only where it added real operational value.

If every single method was enabled for observability, we wouldn’t only get a lot of noise causing the trace trees to be unreadable, but it would also cause the application performance to degrade and quite severely. So balance was the key here.

Annotation Enrichment Model

We standardized on two core OpenTelemetry-related annotations:

@WithSpan for tracing execution boundaries
@SpanAttribute for enriching spans with contextual metadata

To support parameter-level observability, the plugin also required access to method parameter names at compile time. This was enabled by configuring the Java compiler with the appropriate flag: -parameters

This ensured parameter names were retained in the compiled bytecode, allowing them to be used as structured span attributes without manual declaration.

Flexible, Generic Design

Rather than building a narrowly scoped “OpenTelemetry plugin”, we deliberately designed the system as a generic annotation enrichment framework.

Through configuration, we could define:

Which annotations to apply
Where to apply them (class, method, parameter)
Whether parameter names should be automatically mapped as attributes
Which code regions should be included or excluded via regex rules

This made the solution reusable beyond observability — for any future bytecode-level enrichment use case.

Dual-Layer Observability Architecture

The build-time instrumentation layer was combined with a runtime observability stack:

OpenTelemetry Java Agent enabled via JVM arguments
Telemetry exported to a centralized OpenTelemetry Collector
Downstream integration with APM platforms such as Elastic and Datadog

This created a two-layer model:

Compile-time enrichment (our Maven plugin)
Runtime telemetry collection (OpenTelemetry agent)

Outcome: Observability as a Default Capability

Because all legacy applications inherited from a shared Maven parent, adoption was effectively automatic.

No application rewrites were required.
No developer workflow changes were introduced.
Instrumentation became a transparent build-time concern.

Over time, this approach evolved from a legacy modernization technique into a standard part of all new microservice development, effectively making observability a default architectural property rather than an afterthought.

Observability as a Bridge to Microservices

One of the most overlooked benefits of observability is its role as a bridge between legacy systems and microservices architectures.

By instrumenting legacy systems:

Existing workflows become traceable end-to-end
Bottlenecks and coupling points are identified
Candidate services for extraction become clear

This allows organizations to:

Decompose monoliths incrementally
Validate architectural decisions with real data
Reduce risk during migration

In this sense, observability is not just an operational tool — it is a strategic enabler of modernization.

The Human Factor in Transformation

Modernization is not purely a technical challenge. It is also deeply human.

Legacy systems are often maintained by teams who:

Have years of domain expertise
Understand system behavior beyond documentation
Are cautious about disruptive change

Introducing observability in a non-invasive way:

Builds trust within engineering teams
Demonstrates value without forcing immediate change
Encourages gradual adoption of modern practices

Successful modernization efforts recognize that people evolve alongside systems — not in parallel, and not under pressure.

A Pragmatic Path Forward

Organizations do not need to choose between stability and innovation. With the right approach, they can achieve both.

A pragmatic modernization strategy should:

Preserve and stabilize existing systems
Introduce modern capabilities incrementally
Use observability to gain visibility and control
Enable gradual transition toward cloud-native architectures

Observability is one of the first — and most impactful — steps in this journey.

Conclusion

The future of enterprise systems is not built by discarding the past, but by extending it intelligently.

Legacy systems still power some of the most critical operations in finance, insurance, healthcare, and government. Replacing them entirely is often unrealistic. However, leaving them unchanged is equally unsustainable.

By enabling observability through non-invasive techniques, organizations can:

Unlock visibility into complex systems
Reduce operational risk
Accelerate modernization efforts
Build a foundation for scalable, cloud-native architectures

Modernization is not a single event — it is a continuous evolution.
And in that evolution, observability is not just a tool.
It is a bridge between what exists and what comes next.