# opensourcecobol/opensourcecobol4j architecture

> Architecture diagram of the GitHub repository opensourcecobol/opensourcecobol4j, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/opensourcecobol/opensourcecobol4j
- Repository: https://github.com/opensourcecobol/opensourcecobol4j

## Overview

##### Project type and purpose
- This is a source‐to‐source compiler (“opensource COBOL 4J”) that translates COBOL code into Java.
- It contains:
- A C‐based compiler front‐end and back‐end (cobj, parser, codegen)
- A Java runtime library (libcobj) packaged as a JAR
- Auxiliary tools: cobj‐idx (indexed-file utility), cobj‐api (Spring Boot code generator)
- Test suites (NIST COBOL 85) and CI/CD pipelines (GitHub Actions, Docker, .devcontainer)

##### File structure
- Top‐level C compiler:
- cobj/   – scanner (Flex), parser (Bison), AST, semantic checks, code generator modules
- compile_libcobj.sh, Makefile.am/in, configure, autoconf scripts
- lib/   – C support libraries (getopt, gettext), headers (libcobj.h)
- Java runtime:
- libcobj/ – Gradle Kotlin build, Java packages (common, data, file, termio, ui, exceptions, user_util)
- libcobj/app – the main Spring Boot cobj‐api tool
- gradlew, settings.gradle.kts, wrapper files
- CLI tools:
- bin/     – shell wrappers, cobjrun.c
- libcobj/bin – cobj‐api, cobj‐idx executable scripts
- Configuration, docs, CI:
- .devcontainer/ – VS Code remote container setup
- .github/workflows/ – build/test/static analysis pipelines
- doc/          – architecture notes, API references
- tests/        – extensive NIST COBOL85 test inputs and makefiles
- win/          – Visual Studio solution and PowerShell scripts

##### README for additional insights
- The README confirms:
- Compiler front‐end (C) → produces Java source + class
- Runtime library (libcobj.jar) loaded by JVM
- cobj‐idx for indexed file operations
- cobj‐api for generating Spring Boot callers
- Build & install instructions for Linux, Windows, Docker
- CI testing against NIST COBOL85 suite

##### Detail
- Every essential artifact: cobj binary, .java outputs, libcobj.jar, generated .class, cobj‐idx, cobj‐api, test suite.
- Do not over‐abstract: show scanner.l → parser.y, AST modules, codegen.c, config files.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Developer Environment" 
        DEV[".devcontainer"]:::infra
    end
    subgraph "CI/CD Pipeline"
        CI["GitHub Actions"]:::infra
    end
    DEV -->|"push"| CI

    subgraph "Build System"
        AUTOTOOLS["Autotools Build"]:::infra
        GRADLE["Gradle Build"]:::infra
    end
    CI -->|runs configure & make| AUTOTOOLS
    CI -->|runs gradlew| GRADLE

    subgraph "COBOL→Java Compiler (cobj)" 
        SCANNER["Scanner (Flex)"]:::ccomp
        PARSER["Parser (Bison)"]:::ccomp
        AST["AST & Semantic Analyzer"]:::ccomp
        CODEGEN["Code Generator"]:::ccomp
        COBJ_BIN["cobj (compiler driver)"]:::ccomp
        SCRIPT["compile_libcobj.sh"]:::infra
    end
    AUTOTOOLS -->|build| COBJ_BIN
    SCRIPT -->|wrapper| COBJ_BIN
    COBJ_BIN -->|reads scanner.l| SCANNER
    SCANNER --> PARSER
    PARSER --> AST
    AST --> CODEGEN
    CODEGEN -->|"emit .java files"| JAVA_SRC

    subgraph "Java Source & Compile"
        JAVA_SRC["Generated .java files"]:::javaComp
        JAVAC["javac"]:::javaComp
    end
    CODEGEN --> JAVA_SRC
    JAVA_SRC -->|compile with| JAVAC

    subgraph "Java Runtime Library"
        LIBCOBJ_JAR["libcobj.jar"]:::javaComp
        PACKAGES["Packages (common,data,file,termio,ui,exceptions,user_util)"]:::javaComp
    end
    GRADLE -->|shadowJar| LIBCOBJ_JAR
    LIBCOBJ_JAR --> PACKAGES
    JAVAC -->|classpath libcobj.jar| LIBCOBJ_JAR

    subgraph "CLI Tools"
        COBJRUN["cobjrun (bin/cobjrun.c)"]:::ccomp
        COBJ_API["cobj-api"]:::javaComp
        COBJ_IDX["cobj-idx"]:::javaComp
    end
    LIBCOBJ_JAR --> COBJ_API
    LIBCOBJ_JAR --> COBJ_IDX
    COBJRUN -->|runs| LIBCOBJ_JAR

    subgraph "Test Harness"
        TESTS["NIST COBOL85 tests"]:::infra
        TEST_RUNNER["test runner scripts"]:::infra
    end
    TESTS -->|input| COBJ_BIN
    COBJ_BIN -->|output| TEST_RUNNER
    TEST_RUNNER -->|validate| TESTS

    subgraph "Documentation"
        DOC["doc/"]:::infra
    end

    subgraph "Windows Build"
        WIN["win/"]:::infra
    end

    classDef ccomp fill:#ffdddd,stroke:#aa0000,color:#660000;
    classDef javaComp fill:#ddffdd,stroke:#00aa00,color:#006600;
    classDef infra fill:#ddddff,stroke:#0000aa,color:#000066;

    click DEV "https://github.com/opensourcecobol/opensourcecobol4j/tree/develop/.devcontainer/"
    click CI "https://github.com/opensourcecobol/opensourcecobol4j/tree/develop/.github/workflows/"
    click AUTOTOOLS "https://github.com/opensourcecobol/opensourcecobol4j/blob/develop/configure.ac"
    click GRADLE "https://github.com/opensourcecobol/opensourcecobol4j/tree/develop/libcobj/gradlew"
    click COBJ_BIN "https://github.com/opensourcecobol/opensourcecobol4j/tree/develop/cobj/"
    click SCRIPT "https://github.com/opensourcecobol/opensourcecobol4j/blob/develop/compile_libcobj.sh"
    click CSupport "https://github.com/opensourcecobol/opensourcecobol4j/tree/develop/lib/"
    click LIBCOBJ_JAR "https://github.com/opensourcecobol/opensourcecobol4j/tree/develop/libcobj/app/src/main/java/jp/osscons/opensourcecobol/libcobj/"
    click COBJRUN "https://github.com/opensourcecobol/opensourcecobol4j/blob/develop/bin/cobjrun.c"
    click COBJ_API "https://github.com/opensourcecobol/opensourcecobol4j/tree/develop/libcobj/bin/cobj-api"
    click COBJ_IDX "https://github.com/opensourcecobol/opensourcecobol4j/tree/develop/libcobj/bin/cobj-idx"
    click TESTS "https://github.com/opensourcecobol/opensourcecobol4j/tree/develop/tests/"
    click DOC "https://github.com/opensourcecobol/opensourcecobol4j/tree/develop/doc/"
    click WIN "https://github.com/opensourcecobol/opensourcecobol4j/tree/develop/win/"
```
