# graceinfra/grace architecture

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

- Interactive diagram: https://gitdiagram.com/graceinfra/grace
- Repository: https://github.com/graceinfra/grace

## Overview

##### Project type and purpose
- From the README (“grace – Declarative workflow orchestration for the mainframe and hybrid cloud”) and the presence of a Go‐based CLI (cmd/*.go) with subcommands (deck, init, run, submit), this is a command‐line orchestration tool. It reads declarative workflow definitions (grace.yml), applies templates (JCL, YAML), and drives mainframe or cloud deployments via external automation layers (e.g., Zowe).

##### File structure
- Top‐level files
- main.go – entry point that wires the CLI.
- go.mod / go.sum – dependency management.
- cmd/ – each *.go is a subcommand (root, init, init_tui, deck, run, submit) likely using Cobra or a similar framework.
- internal/templates/ – holds Go code + JCL/YML templates for generating deployment artifacts.
- utils/ – cross‐command utilities: execution wrappers, logging, type definitions, Zowe integration.
- No GUI or web frontend; purely CLI + templating + external service calls.

##### Components & Interactions
a. Main Components
1. CLI Frontend (cmd/*) – parses user commands & flags
2. Command Dispatcher – route to appropriate handler (deck, init, run, submit)
3. Core Engine
– Template Manager (internal/templates)
– Workflow Definition Loader (reads grace.yml)
– Execution Coordinator (utils/exec.go)
4. Utilities
– Logging (utils/log.go)
– Type definitions (utils/types.go)
– Zowe Integration (utils/zowe.go)
5. External Services
– Zowe REST API / CLI → Mainframe (z/OS)
– (Optional) Cloud orchestration endpoint (k8s, CI/CD, etc.)
b. Relationships / Data Flows
- User invokes CLI → Command Dispatcher
- Dispatcher loads workflow (grace.yml) → passes to Template Manager
- Template Manager renders JCL/YAML artifacts → saves locally or streams
- Execution Coordinator uses utils/exec or utils/zowe to submit jobs to mainframe or cloud
- Responses / job statuses piped back to CLI → formatted and logged
c. Architectural patterns / principles
- Layered architecture: Presentation (CLI) → Application Logic (dispatcher + core) → Infrastructure (templates + external calls)
- Single Responsibility for each subcommand
- Dependency injection via Go interfaces (e.g., execRunner, zoweClient)
- Templating pattern for artifact generation
d. Key technologies / libraries
- Go Modules
- Cobra (or equivalent) for CLI commands
- Go’s text/template for JCL/YAML generation
- Zowe SDK or CLI (utils/zowe.go) for mainframe interactions

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Main entry
    Main["main.go"]:::module
    click Main "https://github.com/graceinfra/grace/blob/main/main.go"

    %% Command Dispatcher
    RootCmd["cmd/root.go<br>Command Dispatcher"]:::module
    click RootCmd "https://github.com/graceinfra/grace/blob/main/cmd/root.go"

    %% CLI Frontend subcommands
    subgraph "CLI Frontend"
        Init["cmd/init.go"]:::module
        click Init "https://github.com/graceinfra/grace/blob/main/cmd/init.go"
        InitTUI["cmd/init_tui.go"]:::module
        click InitTUI "https://github.com/graceinfra/grace/blob/main/cmd/init_tui.go"
        Deck["cmd/deck.go"]:::module
        click Deck "https://github.com/graceinfra/grace/blob/main/cmd/deck.go"
        Run["cmd/run.go"]:::module
        click Run "https://github.com/graceinfra/grace/blob/main/cmd/run.go"
        Submit["cmd/submit.go"]:::module
        click Submit "https://github.com/graceinfra/grace/blob/main/cmd/submit.go"
    end

    %% Core Engine
    Loader["grace.yml<br>Workflow Definition Loader"]:::config
    click Loader "https://github.com/graceinfra/grace/blob/main/internal/templates/files/grace.yml.tmpl"
    TemplateMgr["internal/templates/templates.go<br>Template Manager"]:::module
    click TemplateMgr "https://github.com/graceinfra/grace/blob/main/internal/templates/templates.go"
    ExecCoord["utils/exec.go<br>Execution Coordinator"]:::module
    click ExecCoord "https://github.com/graceinfra/grace/blob/main/utils/exec.go"

    %% Utilities
    Logging["utils/log.go"]:::module
    click Logging "https://github.com/graceinfra/grace/blob/main/utils/log.go"
    Types["utils/types.go"]:::module
    click Types "https://github.com/graceinfra/grace/blob/main/utils/types.go"
    ZoweClient["utils/zowe.go<br>Zowe Integration"]:::module
    click ZoweClient "https://github.com/graceinfra/grace/blob/main/utils/zowe.go"

    %% External Services
    ZoweService("Zowe REST API / CLI<br>Mainframe (z/OS)"):::external
    CloudService("Cloud Orchestration API<br>(K8s, CI/CD)"):::external

    %% Data flows
    Main --> RootCmd
    RootCmd --> Init
    RootCmd --> InitTUI
    RootCmd --> Deck
    RootCmd --> Run
    RootCmd --> Submit
    RootCmd --> Loader
    Loader --> TemplateMgr
    TemplateMgr --> ExecCoord
    ExecCoord --> ZoweClient
    ZoweClient --> ZoweService
    ExecCoord --> CloudService

    %% Cross-cutting
    Logging -.-> RootCmd
    Logging -.-> TemplateMgr
    Logging -.-> ExecCoord
    Types -.-> RootCmd
    Types -.-> TemplateMgr
    Types -.-> ExecCoord

    classDef module fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef config fill:#FFA500,stroke:#000,stroke-width:1px
    classDef external fill:#90EE90,stroke:#000,stroke-width:1px
```
