Reverse Engineering ADABAS Databases for Modernisation — Why Context Changes Everything
Comparing three approaches to converting a flat-file ADABAS estate into a business-entity-driven relational schema.
Legacy modernisation follows a simple formula: Reverse Engineer → Generate Specs → Build Target. Simple to state. Brutally hard to execute.
I've been building Cortex—an AI-powered modernisation agent for Software AG ADABAS/Natural platforms (introduced here). Cortex started as a maintenance and analysis agent, with a rich business catalog, dependency graph, and semantic search across large Natural estates. Now I'm extending it into a full modernisation agent.
The first major milestone: reverse engineering the ADABAS database—converting a flat-file ADABAS estate into a business-entity-driven relational schema.
Here's what I've learned from experimentation on a demo superannuation fund administration codebase, comparing three approaches:
Three Approaches Compared
Traditional tooling parses DDM definitions and extracts what's structurally visible:
- 104 files, 1,369 fields, 587 descriptors
- MU/PE structures, field formats, descriptor types
What you get: a technical inventory. Field names, data types, lengths.
What you don't get: which fields are MEMBER-ID the foreign key vs. MEMBER-ID the local identifier. You don't know that ACCOUNT-PHASE with values A/P/T represents a state machine transitioning from Accumulation to TTR to Pension. You don't know that INSURANCE-COVER (file 228) contains 6 co-located business entities that need decomposition into separate tables.
Hand an LLM the DDM source files and ask it to reverse engineer entities. It will do a reasonable job on obvious cases—MEMBER-ID is probably a member identifier, ACCOUNT-BALANCE is probably a balance. But:
- It can't tell you that MEMBER is read by 56 modules and written by 19—making it the gravitational centre of the system
- It guesses at foreign keys instead of tracing them through actual FIND/READ statements
- It has no way to know that 384 fields (28%) are never referenced by any module—are they dead fields or served by external systems?
- It invents entity relationships that may not exist in the actual codebase
This is where Cortex transforms the game. The LLM doesn't work from DDM files alone—it works from Cortex's knowledge graph.
Cortex provides the ground truth spine:
- Deterministic CRUD analysis from 437 actual ADABAS access operations (FIND, READ, STORE, UPDATE, DELETE) extracted from Natural source code
- Field-level usage tracking: which module reads which field, in what context (search key, sort key, store, update)
- Call graph and dependency analysis across 90 modules
- Business capability mappings from an SME-annotated catalog
The LLM then adds the meaning layer—grounded in evidence:
Instead of guessing, the agent sees that CONTRIBUTION has fields MEMBER-ID (used as search key in 14 modules), ACCOUNT-ID (FK to Account, used in FIND statements), EMPLOYER-ID (FK to Employer), and CONTRIB-STATUS with values P/A/R and writer module SUBN0317. From this grounded evidence, it derives:
Real Examples of the Difference
Example 1: INSURANCE-COVER (File 228, 26 Fields)
A deterministic tool sees one file. An ungrounded LLM might guess 2–3 entities. Cortex-grounded analysis correctly identifies 6 co-located entities—Account, Cover, Insurance Cover, Insurer Notice, Member, and Transaction—because it traces which modules access which fields and how they flow through the business capabilities.
Example 2: ACCOUNT-PHASE — From Field Inventory to State Machine
A tool sees A(1)—alphanumeric, length 1. An ungrounded LLM might guess it's a flag. Cortex knows the full story:
That's the difference between a field inventory and a reverse engineering document you can actually build from.
The Output: A Migration-Ready RE Document
The Cortex-grounded approach produces a comprehensive reverse engineering document spanning 13 sections:
Document Sections
- Business Entity Catalog
- CRUD Matrices
- Lifecycle State Machines
- Foreign Key Graphs
- Enumeration Catalogs
- ADABAS Construct Analysis (MU/PE)
- Descriptor & Sub-Descriptor Mapping
- Unreferenced Field Gap Analysis
- Entity Decomposition Targets
- Target Relational Schema Derivation
- PostgreSQL DDL Generation
- Migration Risk Assessment
- Source Code Traceability Index
Not a technical dump. A business-entity-driven blueprint for the target PostgreSQL schema—with every entity, relationship, and constraint traceable back to source code evidence.
Side-by-Side Comparison
| Dimension | Deterministic Tool | LLM (No Context) | Cortex + LLM |
|---|---|---|---|
| Entity discovery | 104 (1:1 DDM mapping) | ~80–110 (guessed) | 123 (evidence-based) |
| FK relationships | 0 (not discoverable) | ~50–80 (inferred from names) | 240 (traced through code) |
| Multi-entity DDMs | Not identified | Partially guessed | 70 identified for decomposition |
| State machines | Not discoverable | Sometimes guessed | Derived with writer modules |
| Dead field detection | Not possible | Not possible | 384 fields (28%) flagged |
| Enum → CHECK constraints | Not possible | Partially guessed | 244 values mapped |
| Verifiability | Structurally correct | Unverifiable | Fully traceable to source |
The Principle That Makes This Work
Cortex doesn't replace the LLM. It gives the LLM something no amount of training data can: the actual runtime reality of THIS specific codebase.
The LLM excels at pattern recognition, entity naming, relationship inference, and producing human-readable documentation. But without ground truth, those capabilities produce plausible fiction. Cortex provides the evidence base—437 traced ADABAS operations, field-level usage maps, call graphs, business annotations—that transforms LLM intelligence from speculation into engineering.
What's Next
Database reverse engineering is the first stream of the modernisation pipeline. The second stream—now in progress—is reverse engineering business rules from Natural programs for target application generation.
The same principle applies: deterministic extraction of control flow, decision tables, and data transformations from Natural source code, enriched by LLM interpretation to produce migration-ready specifications for the target platform.