# cicsdev/cics-genapp architecture

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

- Interactive diagram: https://gitdiagram.com/cicsdev/cics-genapp
- Repository: https://github.com/cicsdev/cics-genapp

## Overview

##### Project type and purpose
- This repository is a sample “General Insurance Application” (GenApp) for IBM CICS Transaction Server on z/OS.
- It is a monolithic, COBOL-based transaction processing system driven by 3270 “green-screen” terminals, using IBM Db2 as its data store.
- It demonstrates how to modernize a legacy CICS TS application, exercising various CICS functions (event processing, REXX execs, JCL scripts, WSIM simulation).

##### File structure
- Top-level files: README.md, Changes.md, license and maintainer info.
- “base/” directory contains the core GenApp code and support artifacts:
- base/src/ : COBOL programs (.cbl/.cpy) implementing policy insert/query/delete and setup logic.
- base/cntl/ : JCL job control language scripts to build, bind, delete DB2 packages, install CICS bundles.
- base/data/ : sample data files for load into Db2 tables.
- base/event-bindings/ : CICS event binding definitions (.evbind).
- base/exec/ : REXX exec scripts used in batch or CICS environments.
- base/wsim/ : IBM WSIM definition files (to simulate CICS regions for offline testing).
- base/bin/install.sh : UNIX shell wrapper to orchestrate build and install steps.
- There are README.md files in subdirectories explaining configuration, installation, testing, architecture.

##### README for additional insights
- The root README calls out the purpose: drive a legacy COBOL app through CICS TS, modernize to new features.
- It lists prerequisites: CICS TS, Db2.
- It directs you to base/README.md for detailed instructions on installation, building, testing, architecture.

##### Main components
a. User Interface
- 3270 terminals (green-screen) or a WSIM simulator connecting via TN3270 emulator to CICS TS.
b. CICS Transaction Server (z/OS region)
- Hosts COBOL transaction programs (base/src/*.cbl, .cpy).
- Executes REXX execs from base/exec/.
- Loads event bindings from base/event-bindings/*.evbind.
c. Db2 Database
- Stores insurance policy tables loaded from base/data/*.txt.
- Db2 packages are bound via JCL in base/cntl/*.jcl.
d. Build & Deployment Pipeline
- UNIX/CLI driver: base/bin/install.sh
- JCL scripts in base/cntl to compile, link, bind programs/packages.
e. WSIM Simulation
- WSIM definition files (base/wsim/*.txt) to simulate CICS API calls offline.

##### Relationships and interactions
- 3270 terminal → CICS TS: TN3270 (“start transaction,” display screens).
- CICS TS → COBOL programs: dispatch transaction ID to load the correct module.
- COBOL programs → Db2: SQL calls for INSERT/SELECT/DELETE policy records.
- CICS TS → REXX execs: invoked for environment setup or batch-style operations.
- JCL (batch) → MVS: compiles and links COBOL, binds Db2 packages, loads modules into CICS load library.
- WSIM → COBOL programs: simulates CICS APIs for offline testing.

##### Architectural patterns and design principles
- Monolithic transaction processing architecture (all business logic in COBOL under CICS).
- Clear separation of concerns:
- Transaction logic (COBOL)
- Data definitions (DB2 tables, copybooks)
- Control scripts (JCL, REXX)
- Use of standard IBM mainframe tooling for build/deploy (JCL → MVS batch, CICS bundle install, Db2 package binding).
- Event-Driven: CICS event bindings allow external triggers.

##### Technologies, frameworks, libraries
- IBM CICS Transaction Server for z/OS
- IBM Db2 for z/OS
- COBOL (Micro Focus/EFU)
- JCL (Job Control Language)
- REXX scripting
- IBM WSIM (CICS simulator)

##### Detail level
- Major components without overcrowding:
- 3270 emulator / WSIM node
- CICS TS (with labels for program library, event binding, exec library)
- Db2 (with sample policy tables)
- Build/deploy pipeline (script → JCL → load library)
- Call out important scripts and directories alongside each component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface"
        UI3270["3270 Terminal Emulator"]:::runtime
    end

    subgraph "CICS Transaction Server"
        CICS["CICS TS Region"]:::runtime
        subgraph "COBOL Artifacts"
            COBOL["COBOL Programs (.cbl)"]:::artifact
            Copybooks["Copybooks (.cpy)"]:::artifact
            BMS["BMS Map Definitions"]:::artifact
        end
        EventBindings["Event Bindings (.evbind)"]:::artifact
        REXXExecs["REXX Execs"]:::artifact
        CICS --> COBOL
        CICS --> Copybooks
        CICS --> BMS
        CICS --> EventBindings
        CICS --> REXXExecs
    end

    subgraph "Database"
        Db2["Db2 Policy Tables"]:::runtime
        SampleData["Sample Data Files (.txt)"]:::artifact
        Db2 --> SampleData
    end

    subgraph "Build & Deploy"
        InstallScript["Install Script (install.sh)"]:::build
        subgraph "JCL Jobs"
            DB2CRE["db2cre.jcl"]:::build
            DB2BIND["db2bind.jcl"]:::build
            DB2DEL["db2del.jcl"]:::build
            GeneralJCL["General JCL Jobs"]:::build
        end
    end

    subgraph "Simulation"
        WSIM["WSIM Simulator & Definitions"]:::artifact
    end

    UI3270 -->|"TN3270"| CICS
    WSIM -->|"CICS API Simulation"| COBOL
    CICS -->|"SQL Calls"| Db2
    InstallScript -->|"orchestrates"| DB2CRE
    InstallScript -->|"orchestrates"| DB2BIND
    InstallScript -->|"orchestrates"| DB2DEL
    InstallScript -->|"orchestrates"| GeneralJCL
    DB2CRE -->|"batch compile/bind"| CICS
    GeneralJCL -->|"build & load"| CICS

    click COBOL "https://github.com/cicsdev/cics-genapp/blob/main/base/src/*.cbl"
    click Copybooks "https://github.com/cicsdev/cics-genapp/blob/main/base/src/*.cpy"
    click BMS "https://github.com/cicsdev/cics-genapp/blob/main/base/src/ssmap.bms"
    click EventBindings "https://github.com/cicsdev/cics-genapp/blob/main/base/event-bindings/*.evbind"
    click REXXExecs "https://github.com/cicsdev/cics-genapp/blob/main/base/exec/*.rexx"
    click SampleData "https://github.com/cicsdev/cics-genapp/blob/main/base/data/*.txt"
    click DB2CRE "https://github.com/cicsdev/cics-genapp/blob/main/base/cntl/db2cre.jcl"
    click DB2BIND "https://github.com/cicsdev/cics-genapp/blob/main/base/cntl/db2bind.jcl"
    click DB2DEL "https://github.com/cicsdev/cics-genapp/blob/main/base/cntl/db2del.jcl"
    click GeneralJCL "https://github.com/cicsdev/cics-genapp/blob/main/base/cntl/*.jcl"
    click InstallScript "https://github.com/cicsdev/cics-genapp/blob/main/base/bin/install.sh"
    click WSIM "https://github.com/cicsdev/cics-genapp/tree/main/base/wsim/"

    classDef runtime fill:#e0ffe0,stroke:#008000,stroke-width:1px
    classDef build fill:#e0f0ff,stroke:#0000ff,stroke-width:1px
    classDef artifact fill:#ffe0b2,stroke:#ff8000,stroke-width:1px
```
