Skip to content

How to Scaffold Compilable Spring Boot from Legacy COBOL

Most legacy modernization efforts fail because they feed raw, monolithic COBOL directly into an LLM. This leads to architectural hallucinations, memory leaks, and Java code that simply does not compile.

GitGalaxy flips this paradigm. It uses deterministic mathematical parsing to generate a structurally perfect, 100% Maven-compilable Java Spring Boot architecture first. It maps the memory, wires the REST controllers, and builds the configuration files without human or AI intervention.

Once the scaffolding compiles, each program's business logic is ported into it, either by GitGalaxy's deterministic translator (no model) or by a person or model from a porting ticket, and every port is proven against the original COBOL before a person approves it.

The Java Translation Controller

The cobol-to-java command (gitgalaxy/cobol_to_java_controller.py) ingests the JSON Intermediate Representation (IR) generated by the GitGalaxy COBOL Refractor (cobol-refractor) and orchestrates a suite of specialized Java Forges.

1. Execute the Spring Boot Forge

Point the controller at the _gitgalaxy_clean directory generated during the initial COBOL refraction phase.

cobol-to-java /path/to/legacy_repo_gitgalaxy_clean_20260419 --pkg "com.enterprise.modernized" [--config target.yaml]

2. The Deterministic Translation Pipeline

The engine rapidly constructs a modern microservice architecture through five distinct, deterministic forges:

  1. The Build System Forge: Auto-generates a production-ready Maven pom.xml, a Spring Boot application.yml (for the database the target config names: PostgreSQL by default, or Db2, Oracle, MySQL, H2), and the Main Application class.
  2. The Entity & Memory Forge: Translates complex COBOL byte-maps into strict JPA @Entity classes. It perfectly translates decimal precision, arrays (OCCURS into List<>), and creates transient aliases for memory overlays (REDEFINES).
  3. The API Contract Forge: Detects batch vs. transactional paradigms and generates modern @RestController endpoints, auto-wiring them to newly minted @Service layers.
  4. The EBCDIC Decoder Forge: Automatically generates the EbcdicDecoderUtil necessary to read raw mainframe byte streams. It includes strict hex-boundary validations to safely unpack legacy COMP-3 (Packed Decimal) data without runtime crashes.
  5. The Mock Service Shield: If the legacy code calls an external mainframe subsystem that hasn't been migrated yet, the engine generates a dummy @Service interface. This allows the Spring Context to load successfully without crashing due to missing dependencies.

3. Review the Audit Report

Because the architecture is deterministically generated, every supported target combination is compile-checked: tests/tools/java_target_matrix.py generates CardDemo under 17 configs and runs the real Maven / Gradle build.

==========================================================
 GITGALAXY JAVA SPRING BOOT MIGRATION AUDIT
==========================================================
  • Source Clean Room         : legacy_repo_gitgalaxy_clean_20260419
  • Target Artifact           : legacy_repo
  • Target Package            : com.enterprise.modernized
  • Corporate Header Applied  : Yes

[1] GENERATED CLOUD SCAFFOLDING
----------------------------------------------------------
  • Build & Config Files Forged : 4
  • JPA Entities Generated      : 18
  • REST Controllers Generated  : 12
  • AI Agent Tickets Generated  : 45
==========================================================

You can navigate into the output directory and run mvn clean compile.

4. Port the business logic, then prove it

Each program with business logic gets a porting ticket (ai_agent_jobs/<PROGRAM>_port_ticket.md): the COBOL, the generated classes it must use, and the porting rules. port_runner fills it in one of two ways:

  • --backend det --source-root ESTATE: the deterministic translator. No model; each statement becomes a call into a runtime that follows COBOL's rules byte for byte, and a statement it cannot translate is a named Hole.
  • Any other backend: a hosted, self-hosted or air-gapped model, or a command. A guardrail checks the port against the generated project's inventory.

port_runner prove then runs the equivalence harness: the COBOL under GnuCOBOL (with a CICS model and, for embedded SQL, a real Db2) and the port on the JVM, with the same inputs and injected faults. Outputs, screens, COMMAREAs and Db2 tables must match. A person approves or rejects each proven port.

5. What has been proven

As of 2026-10-02, 48 programs from CardDemo, CBSA and GenApp are proven as deterministic ports (17 of the cases on Db2), and 23 CardDemo programs as model-written ports. The oracle is not z/OS; its known differences are listed in the oracle-assumptions register. See Proven COBOL-to-Java Ports.

Read the full technical specifications: > * Spring Boot Scaffolding * Entity & Memory Mapping * Proven COBOL-to-Java Ports

⬅️ Back to Master Index