How to automate legacy code modernization with AI? A 5-step framework

Legacy application modernization is consulting’s biggest Achilles heel. Your team shows up with a rock-solid blueprint, covering everything from customer origination to event-driven microservices. But every implementation differs from the blueprint grind to an expensive halt:

• Stale documentation masks technical reality: Consultants spend two weeks interviewing teams and inspecting code to reconstruct system capabilities. Worse, engineers struggle with decade-old diagrams abandoned 3 reorgs ago, forcing them to hunt down undocumented edge cases line by line.
• Surface-level discovery misses actual business capabilities: Repetitive walkthroughs with previous consultants lead business experts to describe ideal process flows rather than reality. This way, the shadow workflows and tribal knowledge stays under the wraps before anyone could figure out the flaws.
• Architecture mapping lacks systemic proof: Stakeholder descriptions rarely match the actual codebase, so the team manually browses unfamiliar files, one by one, to verify the implementation. Assuming boundary lines without proof guarantees severe integration failures during cutover.
• Deliverables arrive too late and too shallow: By the time actual insights surface, half the budget is burnt, leaving leadership with high-level slides instead of executable technical specs.

By week 3 you start producing results, but out of a four-week engagement you realistically have one to two weeks of productive work. The output is still high-level: directional enough for executives, not detailed enough for engineering teams to act on.

To break this cycle, we developed a step by step framework that compresses discovery without exhausting the team members. It combines AI-powered legacy modernization with hard architectural evidence, giving development teams a practical modernization method rather than another presentation deck.

Here’s how you can codify the process, map data ownership, and convert the evidence into a bulletproof transition plan.

Step 1: Codify the discovery playbook using spec-kit

Every experienced architect carries a mental playbook. They know the signals to look for, rules for separating business logic from technical plumbing, and exact moments a claim requires line-by-line verification. The catch? That playbook lives entirely in their head.

To make discovery fast and repeatable, you have to extract that tribal knowledge and package it into structured instruction files, exactly what GitHub did with Spec-Kit. This turns spec-driven development into a repeatable discovery method instead of limiting it to greenfield delivery.

If you ask an AI to blindly skim a real-world 200k+ LOC repo for capabilities, you get an unverified, 70% accurate guess. Create your very own automated legacy-system discovery workflow that guides AI agents through predictable, evidence-backed analysis.

We applied the Spec Kit discovery to a client’s digital banking platform. It had 200,000 lines of code (LOC) distributed across microservices and legacy core components. The AI codebase analysis uses strict extraction rules tied to four hard sources of truth:

• Source code & ASTs: Core business logic, annotations, and execution paths.
• API definitions: OpenAPI/Swagger specifications and exposed endpoints.
• Database schemas & migrations: DDL scripts, ORM mappings, and foreign key relationships.
• Infrastructure configuration: Deployment manifests, message queues (e.g., RabbitMQ), and routing logic.

You don't need a running environment or lengthy security approvals for this AI-powered code discovery:

• It runs on commodity AI tools already approved in your stack (e.g., Cursor, GitHub Copilot). You are just supplying structured Markdown prompt files.
• Proven analyzers (like nDepend or JetBrains) extract exact dependency graphs and entry points with 100% precision. Feeding those raw reports into the AI gives you both structural accuracy and domain context for legacy code analysis.
• Domain-driven naming, REST routes, and UI flows mean legacy code becomes readable at scale once you give the AI a codified playbook to parse it.

In just 5 hours, the automation parsed the entire 200,000 LOC codebase and inspected infrastructure boundaries. It then generated 16 locked business capabilities with 90.4% code coverage for legacy architecture discovery.

The capability spec mapped out three clear architectural views for us:

1. Functional scope (Business capability map)

A complete business taxonomy—covering Onboarding, Lending, Payments, and Card Services—mapped directly to live endpoints in the code.

2. System architecture (Context & container views)

A blueprint of actual runtime connections: REST channels, Mambu Core Banking, TM Banking Engine via AMQP, Fourthline KYC, and infrastructure layers like MySQL, RabbitMQ, and Eureka.

3. Data ownership & dependencies

Entity models, cross-capability data flows, and schema boundaries: the exact place where modern architecture plans usually bump into legacy reality.

These findings immediately improved the quality of client conversations. Instead of asking, “How does customer onboarding work?”, the team could instantly see that:

• Customer onboarding integrates with Fourthline for identity verification. What verification flow are you using: document-only or biometric? Are you prepared for upcoming regulatory changes?
• Lending shows two distinct loan products, but no loan origination workflow in the capability map. Is origination handled externally, embedded elsewhere, or not built yet?
• Payments routes international transfers through Wise but has no external provider for domestic. Is that by design, or is there a planned cloud migration to a payment gateway?

Compare that to the traditional approach: "How do you do customer origination?" "What types of loan accounts do you support?" "What types of payments do you support?" Important questions, but ones you can now answer from the report before the first meeting.

The AI tool here is interchangeable. Your methodology is the IP. Once it's executable, discovery starts overnight, inside the client's perimeter, on tools already approved.

Step 2: Extract what the system does (Capability extraction)

Once your discovery playbook is codified, you need an automated pipeline to execute it. In our 200k+ LOC digital banking system, we ran a 7-step capability extraction pipeline.

A1: Seed Candidates (6 steps)
├── A1.1 Package structure analysis
├── A1.2 Database schema analysis        ← skipped if no DB access
├── A1.3 Backend entry point analysis
├── A1.4 Frontend/UI entry point analysis ← skipped if API-only
├── A1.5 Merge signals from all sources
└── A1.6 Candidate list format

A2: Analyze Candidates (per candidate)
├── A2.1 Deep candidate analysis          ← cohesion, coupling, boundaries
├── A2.2 Action determination             ← confirm/split/merge/de-scope
└── A2.3 Consolidate all actions

A3: Verify Coverage
├── A3.1 Coverage check                   ← target >90%
└── A3.2 Orphan resolution

A4: Lock L1 Capabilities
└── A4.1 Finalize L1 list

A5: L2 Sub-Capabilities (per L1)
├── A5.1 Scope L2 candidates
├── A5.2 Refine L2 analysis
└── A5.3 Lock L2 list

A6: Generate Domain Model

A7: Industry Blueprint Comparison

Step A1: Finding candidates from hard signals

The engine extracts signals independently across three layers:

• Package Structure (A1.1): Packages like payments, customers, and lending are strong domain signals. The system flags generic names like processing as ambiguous.
• Database Schema (A1.2): Table clusters, foreign key paths, and stored procedures. Legacy databases often reflect business boundaries far better than the code layer.
• Entry Points (A1.3 & A1.4): REST controllers, message consumers, scheduled jobs, and UI routes.

Crucially, entry points group by business operation: A PaymentController, a RecurringPaymentJob, and a MoneyTransferPage aren't three separate candidates—they are three pieces of evidence for Payments.

On the banking prototype, the pipeline produced 19 candidates with different signal strength:

HIGH (14):
Customer Onboarding
Account Management
Card Services
Payments - Domestic
Payments - International
Bill Payments
Transaction History
Deposits - Personal
Deposits - Group
Deposits - Teen
Lending - Instant Loans
Lending - NOU Loans
Investment Management
Customer Management

MEDIUM (4):
Current Accounts        ← merge with Account Management?
Payments - Scheduling   ← capability or feature of Payments?
Product Catalog         ← business capability or infrastructure?
Gamification            ← no frontend routes, is it active?

LOW (1):
Business Partnerships   ← no frontend, no business logic

Step A2: Candidate analysis & L1 consolidation

Each one gets judged on cohesion, coupling, and boundary clarity, the same lens you'd apply to any proposed service boundary.

Payments - Scheduling had its own microservice, REST controller, and UI route. An AI blindly scanning files marked it as an L1 capability. But structurally, scheduling a payment is just a domestic payment with a frequency parameter.

The pipeline demoted it to an L2 sub-capability under Domestic Payments. Our 19 raw candidates consolidated into 16 locked Level 1 capabilities, passing our 90.4% coverage check (A3).

Step A5: Extracting L2 business operations

Level 1 tells you what the system does; Level 2 tells you what is actionable. We map each L2 down to exact file paths, operations, and entity ownership:

Description:
Manages customer verification via Fourthline integration
(document upload, biometric validation, status tracking).

Key Operations:
├── Create customer via Fourthline (POST /api/v1/origination/verification)
├── Upload identity documents (front/back)
└── Initiate verification jobs & handle callbacks

Code Location:
fourthline-client/.../fourthline

Key Entities:
├── PersonVerification  (OWNS - person_verifications table)
├── FourthlineCustomer  (MANAGES - via Fourthline API)
└── VerificationJob     (TRACKS - via Fourthline API)

External System:
Fourthline (KYC Provider)

Step A6: The consolidated domain model

The final pipeline deliverable is a fully traceable Domain Model:

Digital Banking Platform
├── BC-001: Customer Onboarding
│   ├── BC-001-01: Customer Registration & Account Provisioning
│   └── BC-001-02: Identity Verification & KYC Compliance Requirements
├── BC-002: Customer Profile Management
├── BC-003: Account Management
├── BC-004: Deposits - Personal
└── BC-005: Deposits - Group

This traceability turns abstract diagrams into execution scopes. Saying "the system handles Payments" is presentation fluff. Showing that Payments spans 32 files across 2 packages, owns 4 entities, exposes 8 endpoints, and depends on Account Management through TransferService.cs gives your team an exact migration boundary.

This granular mapping also drastically improves AI analysis. If a client needs deep business rules for payments or lending, pointing an AI assistant at a 200,000-line codebase yields poor results. Instead, point Cursor or Copilot directly at the 32 relevant files.

Restricting the AI to a focused scope produces cleaner specs, accurate validation logic, and reliable business rules. Scope the boundary first, then extract the details.

Step A7: Benchmarking against BIAN

Finally, we run the code-derived domain model against industry reference architectures (like BIAN for banking or TM Forum for telecom). In our banking prototype, BIAN alignment confirmed our core domain structures while surfacing critical gaps: fraud detection and regulatory reporting had zero code matches. This prompted immediate, high-value client questions: Are these capabilities handled by external third parties, or are they entirely missing?

Why Does a Pipeline Beat a "Single Prompt" Approach?

To test the pipeline's value, we ran the same 200k LOC codebase through Claude Sonnet 4.6 using a single, highly detailed prompt. The single prompt found all 28 services, counted LOC correctly, cataloged every controller and entity.

But compared to the pipeline's domain model, roughly half the L1 capabilities matched and under half of L2s mapped to actual business sub-capabilities. The other half were channels, infrastructure, and tooling classified as business functions:

├── Mobile Banking Channel      ← Delivery channel (43% of codebase), not a capability
├── Core Banking Integration     ← Infrastructure layer
├── Administration & Oversight  ← Internal tooling
└── Product Catalog              ← Infrastructure dependency

A half-right model is dangerous: it looks credible enough to be nodded through by executives, but leads to disastrous architectural boundary errors during cutover. Multi-step pipelines enforce explicit review gates, turning speculative LLM guessing into predictable, production-ready discovery.

Step 3: Discover the system architecture (C4 model pipeline)

After mapping business capabilities, you need to understand how the application is physically built. We use Simon Brown's C4 architecture documentation model for legacy system assessment here:

• L1: System Context: Where does the system sit in the enterprise? Who uses it, and what external systems does it touch?
• L2: Containers: What are the runtime units (microservices, databases, gateways)? How do they deploy and talk to each other?
• L3: Components: What is inside each container? How are classes, packages, and layers structured?
• L4: Code: How is the logic implemented at the class or method level (reserved for high-risk areas)?

Asking an AI to generate a C4 architecture documentation from a 200,000 LOC codebase in a single prompt yields unreliable results. Instead, we run a three-phase pipeline where each step reads one artifact and feeds the next:

D1: C4 System Context (L1)
├── D1.1 Consolidate entry points
├── D1.2 Extract actors
├── D1.3 Extract external systems
├── D1.4 Map relationships
├── D1.5 Generate context draft
└── D1.6 Lock context diagram

D2: C4 Containers (L2)
├── D2.1 Scan deployment config
├── D2.2 Identify containers
├── D2.3 Re-classify infra
├── D2.4 Map container communication
├── D2.5 Generate containers draft
└── D2.6 Lock containers diagram

D3: C4 Components (L3) – Per Container
├── D3.0 Select container
├── D3.1 Scan package structure
├── D3.2 Component inventory
├── D3.3 Detail each component
├── D3.4 Map dependencies
├── D3.5 Logical view diagram
├── D3.6 Physical view diagram
├── D3.7 Traceability matrix
├── D3.8 Documentation draft
└── D3.9 Lock documentation

L1: System Context (Where Does the System Live?)

Context is all about system boundaries. Before planning a migration, you must know where your application ends and external systems begin. We resolve context dependencies by analyzing three evidence sources:

1. Configuration files: We extracted base URLs, connection strings, and message queues, immediately revealing 9 external systems.
2. Legacy dependency mapping: Files like pom.xml, package.json, and *.csproj cross-validate technologies (e.g. spring-amqp confirms RabbitMQ, aws-java-sdk-s3 confirms S3).
3. Inbound entry points: Scanning REST controllers, message consumers, and frontend routes identifies who initiates interactions.

It also reads entry points through authentication patterns: /admin/* paths with role-based auth indicate internal admin users; inbound API key auth signals business partners; frontend routes with passcode logins map to end customers. The engine also identified four distinct actors: end customers, prospects, internal admins (/admin/*), and business partners.

L2: Containers (What Is Actually Deployed?)

Container analysis defines system topology: the physical, deployable runtime units. We identified candidate containers by scanning deployment configs:

• Docker & Kubernetes Files: docker-compose.yml, per-service Dockerfiles, and kustomization manifests.
• Build Pipelines: Jenkinsfiles, GitHub Actions workflows, and GitLab CI configs.
• Application Entry Points: @SpringBootApplication classes, Program.cs builders, and package.json scripts.

This scan identified 26 application containers: 2 UI applications (Mobile App in React Native, Admin Panel in React/Nginx) and 24 backend Spring Boot microservices running Java 17.

We also reclassified infrastructure items (databases, message brokers, service registries). If a component is self-hosted with local Kubernetes manifests and application-specific data, it is reclassified from an external service to an internal container.

You can move both Eureka and MySQL to internal containers based on this rule.

INTERNAL CONTAINER (move from External to Container)

├── Listed in docker-compose as a service
├── Has Kubernetes deployment in our manifests
├── Self-hosted (we manage it)
└── Data is application-specific


EXTERNAL SYSTEM (keep as External)

├── Managed cloud services (AWS RDS, SQS, Azure Service Bus)
├── Third-party SaaS (Stripe, Twilio, Auth0)
└── Corporate shared services (enterprise SSO, logging)

Code analysis across the 26 containers revealed three distinct structural patterns:

• Integration gateway: Core Banking Service sits between all domain services and external banking engines. Eleven services call Core Banking, which routes to Mambu or TM depending on the runtime flag.
• Aggregator pattern: Account Summary fans out to six product services in parallel using Feign client interfaces to aggregate a unified portfolio view.
• Shared database pattern: 19 backend services connect to one MySQL instance. While each service has its own logical schema, they share physical storage.

L3: Components (What Is Inside Each Container?)

Component analysis goes inside each container, one at a time, sequenced by business criticality. We started with customers-origination (customer registration through KYC verification). Scanning customers-origination produced a clear, layered component breakdown:

Scanning the file inventory instantly surfaced zero test files across every single layer of this core onboarding service. Step D3.2 splits the container inventory into business components (derived from capabilities) and technical components (derived from package structures).

Now we can extract responsibilities, enforcing classes, and known risks. For BUS-COMP-001: CustomerOnboarding Orchestration (21 production files, 3 integration test files):

Tracing the registration execution path in D3.4 revealed extreme coupling across five synchronous hops:

CustomerOriginationController
    └── CustomerServiceImpl
            ├── Customers Service (validate/create)
            ├── Core Banking Service (TM/Mambu account)
            ├── Current Account Service (provision primary account)
            ├── Wise Service (payment profile – optional)
            ├── CRM Service (lifecycle event – async)
            └── Gamification Service (onboarding quest – async)

For each container, the pipeline produces two distinct views:

1. Logical view: Shows business components, actor interactions, and external dependencies. Designed for executives, product owners, and migration planning.

2. Physical view: Maps layers, package structures, and physical dependencies. Designed for developers refactoring the code.

In approximately 5 hours, the pipeline produced complete, multi-level C4 documentation across the entire 200,000 LOC codebase:

• Full L1 system context with external dependency mapping.
• L2 container topology covering 26 services, identifying shared databases and integration bottlenecks.
• L3 component deep dives across 19 containers, complete with business rules linked to code methods, zero-test coverage flags, and synchronous coupling risks.

By letting automated pipelines extract and document the raw facts, your architects can spend their time on what actually matters: evaluating risks, making decisions, and planning the target architecture.

Step 4: Extract data ownership & map schema boundaries

Architecture plans inevitably collide with reality at the data layer. You can draw clean microservice boundaries on a whiteboard, but if three services perform direct SQL joins against a shared table, your decoupling strategy will fail during migration.

You need to extract the data topography across the 200,000 LOC codebase to answer:

• Who owns what data?
• How do services share entities?
• Where are the cross-capability schema dependencies?

E1: Extract Local Schemas (Entities, DDLs, ORM Mappings)
└── E2: Classify Data Ownership (OWNS vs. MANAGES vs. READS)
    └── E3: Map Cross-Capability Data Flows & Shared Entities
        └── E4: Generate Target Data Migration Boundaries

Instead of inspecting database tables manually, the pipeline scans ORM mappings (JPA/Hibernate annotations, .hbm.xml files), DDL scripts, and SQL migration files (Flyway/Liquibase).

The pipeline classifies entity interaction using a strict ownership hierarchy:

• OWNS: The service controls the primary database table, holds schema migration rights, and writes directly to the entity.
• MANAGES: The service updates entity states via external API contracts (e.g., third-party providers).
• READS: The service queries entity data via read-only views, shared connections, or API projections.

Create the ownership matrix by scanning our digital banking prototype. It surfaced 42 core database entities across 19 relational schemas in our single MySQL instance:

Because 19 backend services share one MySQL instance, physical data isolation does not exist. Step E3 cross-references SQL queries, repository classes, and foreign key definitions to map hidden coupling.

Scanning revealed three severe data-layer risks:

• PaymentTransaction in the Payments database holds direct foreign key constraints referencing accounts in the Account Management database. You cannot extract Payments into an isolated database without breaking referential integrity at the database level.
• Raw SQL joins directly queries the Person entity (owned by Customer Profile Management) by five separate microservices:
  • Customer onboarding (Validates identity)
  • Domestic payments (Validates payee name)
  • Instant loans (Calculates credit risk)
  • Card services (Prints cardholder name)
  • Transaction history (Enriches customer statements)

[Customer Service] (OWNS Person Entity)
│
├──► [Onboarding]
│    └── Access: Direct SQL
│
├──► [Payments]
│    └── Access: Direct SQL
│
├──► [Lending]
│    └── Access: Direct SQL
│
├──► [Cards Service]
│    └── Access: Direct SQL
│
└──► [Transaction History]
     └── Access: Direct SQL

Step 5: Build an executable transition plan

Discovery is useless if it ends in a static presentation deck. So we need to merge the outputs of capability specs, C4 models, and data ownership matrices into a prioritized, risk-ranked legacy migration roadmap:

T1: Calculate Complexity & Debt Scores (Per Component)
└── T2: Determine Decoupling Order (Strangler Fig Migration)
    └── T3: Define Execution Slices & Coexistence Architecture
        └── T4: Generate Target State Migration Roadmap

We score each Level 1 capability using four code-backed metrics:

• Inbound/Outbound coupling: Number of synchronous Feign calls and cross-domain DB queries.
• Test coverage deficit: Percentage of files lacking unit or integration tests.
• Data dependency risk: Shared tables, direct foreign keys, and cross-schema joins.
• Business impact: Revenue path criticality and regulatory requirements.

This way, we can create a migration matrix to save time and improve ROI:

Wave 1: Low hanging fruit

Target: Card Services

Why: Zero cross-domain foreign keys, clear REST boundaries, low business risk. Perfect for validating your modern deployment pipeline.

Wave 2: High value, medium complexity

Target: Customer Onboarding (BC-001).

Why: Despite its high business impact, the team can decouple downstream calls into asynchronous events via a Strangler Fig migration.

Wave 3: Complex core domains

Target: Domestic Payments & Account Management.

Why: Heavy database coupling requires data-refactoring sprints (introducing event-driven CDC via Debezium) before physical decoupling.

For each wave, the framework generates an actionable execution specification for engineering teams:

1. Pre-Prerequisite Refactoring (Sprint 1–2):
├── Add unit tests to CustomerServiceImpl (Target: 80% coverage)
└── Wrap Fourthline KYC API calls with a Resilience4j circuit breaker

2. Data Layer Decoupling (Sprint 3):
└── Onboarding no longer queries the 'persons' table directly at write-time;
    it consumes 'PersonCreated'/'PersonUpdated' events from Customer Profile
    Management (BC-002) via RabbitMQ and builds a local read-cache

3. Strangler Fig Routing (Sprint 4–5):
├── Deploy new Onboarding Microservice alongside legacy
├── Route 10% of POST /api/v1/origination/customers traffic via API Gateway
└── Monitor error rates and rollback automatically if latency exceeds 200ms

What’s next? The future of legacy modernization with AI

Modern AI modernization framework fails because discovery relies on human memory, stale documentation, and manual code inspection. By replacing manual discovery with a spec-driven methodology, you transform the entire engagement model:

• Speed: Compress 3 to 4 weeks of exploratory interviews into 5 hours of automated extraction.
• Accuracy: Shift from 70% unverified guesses to 90%+ code-backed certainty.
• Actionability: Move from executive slide decks to executable technical specifications linking business capabilities directly to source code lines, database schemas, and migration steps.

The AI tools you use will continue to evolve, but your discovery methodology remains your core intellectual property. Codify your playbook, execute structured extraction pipelines, and turn your modernization processes into a predictable science.