DEV Community

Cover image for How We Integrate Legacy Systems With Modern Stacks
Rylko Roman
Rylko Roman

Posted on

How We Integrate Legacy Systems With Modern Stacks

#legacy #stacks #system #integration

Integrating with legacy isn’t “old vs. new.” It’s gravity. You have a system that has carried the business for years—imperfect, undocumented, but revenue-critical. Then leadership asks: “We need a mobile app, partner APIs, real-time analytics, maybe an LLM search—without breaking what works.” Familiar?

Across insurance, logistics, fintech, e-commerce, and B2B platforms, we’ve integrated COBOL/AS-400, Oracle Forms, “Spring 3 monoliths,” and homegrown CMSs with modern services. Tooling differs, but the pattern that works for us is surprisingly consistent. Below is what actually moves projects forward in production. At the end, I’ll share the single approach I recommend to nearly everyone facing legacy integration.

The Core Philosophy: “Squeeze Gently”

We don’t “rewrite everything.” We wrap legacy in an Anti-Corruption Layer (ACL) and expose a thin, stable contract (API + events). Around that contract, we build new services and strangle capabilities out of the monolith step by step (the classic strangler fig pattern). The devil is in the details: stopping direct DB coupling, keeping transactions honest, preserving history, and hitting SLAs.

Common Traps (and What We Do Instead)

1) “Let’s design the perfect domain model first.”

Don’t. There’s always a column like status_code=42 that only “Peter who left in 2017” remembers. Start contract-first from business needs: what must the outside world see (mobile app, partner portal, reports)? Fix that API first; then map it to legacy.

Practice: Contract-first + Consumer-Driven Contracts (CDC tests). We agree a JSON/gRPC schema and ship contract tests. Any accidental field change breaks CI.

2) “Reading the legacy DB directly is fastest.”

Fast, yes. Fragile, absolutely. Legacy schemas change without notice, transactions are sticky, and “two joins” turn into a six-hour nightly ETL. We avoid binding new components to raw tables. Between “them and us” sits an ACL/Legacy Adapter that translates the legacy dialect into a clean domain model.

Practice: A small legacy-adapter service. Inside: gnarly mappers and vendor quirks. Outside: clean DTOs. It’s “another layer,” but it localizes chaos.

3) “We must stay synchronous or we’ll lose consistency.”

False dichotomy. For money paths (payments, policy issuance) we keep synchronous + idempotent flows with detailed auditing. For everything else (search, notifications, work queues, analytics) we go event-driven and eventually consistent.

Practice: Change Data Capture (CDC) via Debezium/GoldenGate/LogMiner → Kafka/Pub/Sub → normalization → read-optimized projections. You don’t crack open legacy code; you stream changes from the DB log and feed the new world.

4) “Let’s build the perfect lakehouse first.”

Build only what the product needs now. For Monday morning reports, start with a nightly pipeline and a “dirty but labeled” mart. For real-time UX, create a narrow projection for the 3–5 entities that matter. After a month you’ll know what deserves hardening.

Practice: Lightweight data model: 2–3 CDC streams → 1–2 projections for UX/BI; schema versioned with migrations; data contracts documented.

5) “The new service can reuse legacy credentials—it’s practical.”

Practical, but risky. Put legacy behind an API gateway, scrub access, and upgrade authn/z: mTLS, OAuth2/OIDC, short-lived tokens; secrets in a vault, not in configs. Internally: RBAC/ABAC. Externally: rate limits and scoped keys for partners.

Step-By-Step: How We Actually Integrate “Old” With “New”

Step 0 — Map What Exists

  • Flow map: who writes/reads DBs, which nightly jobs run, which reports are “wind-sensitive.”
  • Non-negotiables: where you truly need strong consistency (money, inventory) and where eventual consistency is fine.
  • Risks: heroic tables with one keeper, batch scripts with no owner, Excel exports powering finance.

Step 1 — Contract-First and a “Thin Neck”

  • Freeze the external contract (REST/gRPC/GraphQL + events).
  • Ship contract tests and real consumer scenarios (app, partner, BI).
  • Build the ACL/Legacy Adapter translating between the contract and legacy.

Step 2 — Observability First

  • Tracing and SLOs: success rate, latency, error budget; dashboards for event flow.
  • Sandwich logging in the adapter: inbound contract ↔ legacy dialect.
  • Idempotency keys, de-duplication, outbox pattern for safe publishes.

Step 3 — Data Without Surgery

  • Turn on CDC from the production DB (with DBA blessing).
  • Normalize change events into domain topics; build projections for reading.
  • For LLM/RAG search, create a separate index; the source of truth remains legacy.

Step 4 — Strangle Capabilities Outward

  • Pick one zone (e.g., stock availability). Build a new service + cache around it.
  • Shift a slice of traffic with feature flags/canary. Watch SLOs.
  • Repeat. In 6–12 months the monolith quietly shrinks; the business already runs on the new perimeter.

Step 5 — Change Hygiene

  • Version contracts (v1/v2 with end-of-life dates).
  • Change management: RFCs, a clear owner, a rollback plan.
  • Keep short ADRs (1–2 pages) for architectural decisions.

A Real Story: Insurance + Warehouse + Mobile

Monolith on Java 6, heavy Oracle schema, nightly ETLs, Excel reports. The business needed a mobile app for agents and a partner API, but full rewrite was a non-starter.

What we shipped:

  1. External contract: 14 endpoints + 6 events (“policy.created,” “status.changed,” “reservation.released”).
  2. Legacy Adapter: a separate service. Inside—PL/SQL mappers and manual transactions. Outside—clean DTO, idempotency, audit.
  3. CDC: redo log capture → Kafka → two projections: mobile (low-latency reads) and BI (fresh reporting).
  4. Security: OAuth2, short-lived tokens, partner scopes, mTLS to the adapter; old point-to-point integrations moved behind the gateway.
  5. Strangling: first read-only statuses, then requests (with idempotency), then tariff calculation via a new microservice + cache.
  6. Results: in 4 months we delivered the partner API and mobile app on a modern stack, had zero money incidents, cut night ETL from 6h to 1h, and kept legacy changes minimal.

The “Modern” Tools That Actually Help

  • CDC + events instead of reading someone else’s tables: Debezium or cloud alternatives → Kafka/Pub/Sub.
  • Anti-Corruption Layer as a microservice translator. You don’t need the “perfect monorepo.” You need isolation of weirdness.
  • Short-TTL caching + idempotency. A 60–120s cache can raise UX quality dramatically without pretending everything must be strongly consistent.
  • Feature flags, canary, shadow traffic. Don’t pull a big switch; flow into the new path.
  • Observability as a product. Business SLOs at the top (“issue policy < 3s”); technical metrics at the bottom; simple alerts to avoid pager hell.
  • Security by default. Short-lived credentials, signed events, least privilege scopes.

The Single Approach I Recommend to Almost Everyone

Strangler + ACL + CDC.

In plain terms: a clean, stable external contract; a translator layer shielding the mess; and change events streaming from the DB log.

Why it works:

  1. Minimal revenue risk. You don’t operate on the heart; you build arteries around it.
  2. Predictable cost. Small, measurable iterations. Each slice pays for itself.
  3. Decoupling from internal quirks. Legacy can evolve or wobble—your external contract stays stable.
  4. Future-ready. Today you add mobile; tomorrow, LLM search or anti-fraud—contracts and events are already there.
  5. Team discipline. ACL localizes dirt, CDC provides a shared truth bus, contract tests stop accidental breakage.

A 6–8 Week Starter Plan:

  1. Agree the external contract for the first 3–5 flows.
  2. Stand up the ACL/Legacy Adapter with idempotency and basic authz.
  3. Enable CDC for two or three high-value tables; build one read projection.
  4. Expose the first read-only scenario via API + events.
  5. Turn on feature flags + canary; practice rollback.
  6. Lock SLOs and basic observability (tracing + 5 actionable alerts).

After this, you own a thin neck through which you can pull functionality out of the monolith without shutting down the business.

“What If It Breaks?”

We always keep three safety nets:

  • Two-way switch (router/flag): return traffic to the old path in under a minute.
  • Duplicate journal (outbox/integration log): every operation is replayable.
  • Minimum-damage principle: money paths stay synchronous + idempotent; everything else is async where failure means degraded UX, not CFO-level incidents.

Practical Recommendations If You’re Starting Now

  1. Contract first. Don’t argue tables—agree on JSON/gRPC.
  2. Assign an ACL owner. It’s “dirty work” that saves months.
  3. Enable CDC. Even if you’re not ready for a full event bus, start streaming and storing changes. You’ll thank yourself later.
  4. Pilot narrowly. One scenario. One traffic slice. One clear SLO.
  5. Invest in observability. Without it, debates devolve into “legacy vs. new” blame games.
  6. Version discipline. Version contracts; set retirement dates; communicate them early.
  7. Business communication. Package each iteration as a business win: “form time −40%,” “integration errors −60%,” “report at 9:00 instead of 12:00.”

Closing

Legacy integration isn’t a generational war; it’s an architecture of compromise. You don’t defeat the old system—you teach it a new language with grammar (the contract), a dictionary (the ACL), and mail (events). In a few months, the business will operate on the new perimeter while the monolith quietly powers down piece by piece.

If you remember only one thing, let it be this: Strangler + ACL + CDC. Start small. Keep a canary and a rollback flag. Measure SLOs. You’ll be surprised how willing “the old” is to work with “the new” when you speak to it correctly.

About me

Here are a few of my recent features in major outlets:

https://www.cio.com/article/4064316/31-of-it-leaders-waste-half-their-cloud-spend.html

https://www.cio.com/article/4059042/it-leaders-see-18-reduction-in-it-workforces-within-2-years.html

Best regards,
Roman Rylko
CTO at Pynest (Dallas, TX) - https://pynest.io
LinkedIn - https://www.linkedin.com/in/roman-rylko/

Top comments (0)